Swagger

Rest Api 文档自动生成工具 Swagger

---

swagger常用注解

@EnableSwagger2Doc

Application 类上加注解 @EnableSwagger2Doc 启用 swagger，这个注解是 swagger-spring-boot-starter 包提供的，内部包含自动配置类。

@Api 注解 Controller 类名

tags 标题，不同 controller 可以使用同一个 tags，这样 swagger 界面上多个 controller 中的接口会合并到一起。

@ApiOperation 注解 Controller 方法

@Api controller类名 描述controller
@ApiOperation controller方法 描述接口方法

@Slf4j
@RestController
@Api(tags = "Info系统接口")
public class InfoController extends AbstractRestController {
    @ApiOperation("编辑信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "infoId", value = "信息ID", example = "1234567"),
            @ApiImplicitParam(name = "name", value = "名字", example = "masikkk")
    })
    @PostMapping(value = "/info/edit/{infoId}")
    public APIResult editInfo(@PathVariable("infoId") long infoId,
                                    @RequestParam("name") String name) {
        log.info("Enter method editInfo, infoId: {}, name: {}", infoId, name);
        APIResult restResponse = infoService.editInfo(infoId, name);
        log.info("End method editInfo, response: {}", JsonUtils.toJson(restResponse));
        return restResponse;
    }}

@ApiParam 注解 Spring MVC 参数

@ApiParam 注解通常用于描述被 @RequestParam, @PathVariable 等 Spring MVC 注解标记的 path 或 param 方法参数。它允许你提供参数的描述、是否必须、示例值等额外信息，这些信息会显示在生成的 Swagger UI 文档中。

@GetMapping("/users/{id}")
public User getUserById(@ApiParam(value = "用户的ID", required = true, example = "1") @PathVariable Long id) {
    // ...
}

@ApiImplicitParam 注解方法级参数

@ApiImplicitParam 注解用于在方法级别描述 API 的参数，特别是当参数不是直接作为方法参数传递，而是通过其他方式（如请求体）传递时。这个注解通常与@ApiImplicitParams（用于描述多个参数）一起使用，并放置在 API 方法上。

@ApiImplicitParams({
    @ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User", paramType = "body")
})
@PostMapping("/users")
public User createUser(@RequestBody User user) {
    // ...
}

@ApiModel 注解参数类

@ApiModel 注解参数类

@ApiModel 的 value 会覆盖类名

默认参数类的名字是类名 UserInfo，如果 @ApiModel 指定了 value 则名字是“用户信息”

@ApiModel("用户信息")
public class UserInfo {
}

如果想在 @ApiModel 加注释但又不影响 swagger 参数类的名字，应该使用 description 参数，比如：

@ApiModel(description = "用户信息")
public class UserInfo {
}

@ApiModel 注释类的继承问题

如下父类上有 @ApiModel 注解但子类上没有，则 swagger 生成的 SubClass 只有父类 BaseClass 中的字段，解决方式是在子类上也加上 @ApiModel 注解。

public class SubClass extends BaseClass {
}

@ApiModel(description = "父类")
public class BaseClass {
}

@ApiModelProperty 注解参数类字段

@ApiModelProperty 注解参数类字段

@Data
@ApiModel(description = "档案查询条件")
public class ArchivesQueryVO {
    @ApiModelProperty(value = "档案ID")
    private List<String> archiveId;
}

java.lang.NumberFormatException: For input string: “”

对于标注了 @ApiModelProperty 的 Integer long 等字段， swagger 在给其生成默认值的时候，会读取 example 值，这个 example 默认是 空字符串，转为 整型 或 Long 型 时 Long.valueOf() Integer.valueOf() 方法会报错。加上数字默认值就行了。

@Data
@ApiModel(description = "接口返回")
public class ResponseDTO {
    @JsonProperty("rtn")
    @ApiModelProperty(value = "返回码", example = "200")
    private Integer rtn;

    @JsonProperty("message")
    @ApiModelProperty(value = "描述信息")
    private String message;
}

@ApiIgnore 屏蔽方法/参数/字段

@ApiIgnore 可用在方法上，类上，参数上
如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。
1、屏蔽 delete 方法

@ApiIgnore
public boolean delete(@PathVariable("id") int id)

2、屏蔽 pageable 参数

@ApiOperation(value = "查询")
@ApiImplicitParams({ @ApiImplicitParam(name = "page", value = "当前页码"),
        @ApiImplicitParam(name = "size", value = "每页数据条数"), })
@GetMapping("/user/query")
public APIResult<List<UserVO>> query(QueryVO queryVO, @ApiIgnore @PageableDefault Pageable pageable) {
    List<ArchiveVO> page = service.queryUser(queryVO, pageable);
    return RestOuts.ok(page);
}

---

No operations defined in spec!

打开 swagger 页面时提示 No operations defined in spec!

原因是突然改了包名

spring.swagger.base-package=com.xx.package 配置的根路径不存在了，所以swagger扫描不到api

---

SpringBoot 中使用 Swagger 生成 API 文档

maven 引入 swagger 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>

<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.4.5-RELEASE</version>
</dependency>

springfox-swagger2 负责扫描所有 swagger 注解生成 json 格式的 api 文档
springfox-swagger-ui 根据 json 文档 生成 html 页面

json数据地址和ui界面地址

启动项目后打开
http://localhost:8080/v2/api-docs
能看到 json 格式的接口描述

http://localhost:8080/swagger-ui.html
查看 ui 界面

Spring Boot中使用Swagger2构建强大的RESTful API文档 - 程序猿DD
http://blog.didispace.com/springbootswagger2/

contain-auth-header 自动添加认证header

swagger.contain-auth-header: true 是否自动添加认证 header, 默认是 false
如果开启了此配置项 , 会自动添加 account, signature, requestTime 这三个 header 参数，不需要的话不要设为true。

配置示例：

swagger:
  enabled: true
  title: MyApiDoc
  basePackage: com.masikkk
  contain-auth-header: true

---

导出 Swagger 文档

前提是项目已经开启了 swagger 依赖，能够导出 json 格式的 swagger 数据。
开启 swagger 后， http://localhost:8080/v2/api-docs 就是 json 数据地址，或者如果有 swagger-ui 界面，在主页左上角有此链接。

---

Swagger2Markup

Swagger2Markup 是 Github 上的一个开源项目。该项目主要用来将 Swagger 自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

Swagger2Markup 项目是将 swagger 文档导出为其他格式的基础。

Swagger2Markup / swagger2markup
https://github.com/Swagger2Markup/swagger2markup

---

spring-swagger2markup-demo

我们将 swagger 导出为 pdf、html、markdown 格式都需要用到 Swagger2Markup 项目，但这个项目配置比较麻烦，所以官方给出了一个 demo 项目。

有了这个项目，我们只需要将自己的 swagger 数据保存为 json 文档，然后填入这个项目的配置属性，运行下 test 就好了。

Swagger2Markup / spring-swagger2markup-demo
https://github.com/Swagger2Markup/spring-swagger2markup-demo

---

导出为pdf或html

1 下载 Swagger2Markup / spring-swagger2markup-demo 项目，倒入为 maven 项目，等待 maven 下载依赖完成。
2 将自己的 swagger 数据保存为 api-docs.json
3 修改 spring-swagger2markup-demo 项目的 pom 文件，找到配置项 <swagger.input>，改为自己 json 文档地址，绝对目录或相对目录都行。
4 执行 mvn test 命令，不报错的话，在项目下的 target/asciidoc 目录就能找到生成的文档。

其实，这里的 mvn test 包含两个步骤：
第一步将 json 转为 ASCIIDOC 格式。
第二步，将 ASCIIDOC 转为 pdf 和 html 格式。

使用中发现生成的 pdf 中有的中文字符不显示，但 html 是好的，可以先浏览器打开 html，再打印为 pdf 即可。

导出swagger2生成的文档
https://www.cnblogs.com/zeussbook/p/11091520.html

导出为markdown

默认情况下，Swagger2Markup 将 json 渲染为 asciidoc 基本文档格式，然后再转为 pdf 或 html 格式。
如果我们想转换为 markdown 格式，只需要修改一个参数即可
修改 spring-swagger2markup-demo 项目的 pom 文件，找到 swagger2markup-maven-plugin 插件的配置项 <swagger2markup.markupLanguage> 默认是 ASCIIDOC 改为 MARKDOWN，然后执行 maven 插件的构建过程即可。
这次我们不需要执行 mvn test 只执行第一步即可。

Spring Boot 2.x基础教程：Swagger静态文档的生成
https://aijishu.com/a/1060000000017742

Failed to execute goal ‘convertSwagger2markup’

首次执行时报这个错，原因是 swagger2 导出的 json 文档不规范，少了几个必须的字段，导致 Swagger2Markup 执行失败。

1 首先，可以用官方的 json 文档试一下，如果没问题，就说明 spring-swagger2markup-demo 项目配置是没问题的。
官方json示例
https://petstore.swagger.io/v2/swagger.json

2 打开官方提供的一个 swagger 编辑器
https://editor.swagger.io/
把自己的 json 帖进去，右边会告诉你格式不准确的地方。
如下图，我这里生成的 json 就是缺了 title, version, license.name 属性，导致无法生成文档，加上就好了。

editor.swagger.io

右边下面还会提示好多编码错误，不用管，只把缺字段的补上就好了。

---

Api2Doc

Swagger 比较臃肿，不太友好，偶然发现一个 Api2Doc 项目，和我们平常工作中用的 ShowDoc 文档非常相似，简洁又清晰。

terran4j/commons
https://github.com/terran4j/commons/tree/master/commons-api2doc

还在用 Swagger2 生成 Restful API 文档？来试试 Api2Doc 吧
https://my.oschina.net/u/3017144/blog/1679922

用Api2Doc代替Swagger2生成 Restful API 文档
https://www.jianshu.com/p/281df3ecd3b0

---

apidocx

https://github.com/jetplugins/apidocx

---