使用SpringDoc生成接口文档

SpringDoc是用于生成SpringBoot项目API文档的Java库。在代码中使用swagger-api注解，即可生成相应的API文档，和JavaDoc非常类似。

SpringDoc基于Swagger 3，Swagger 3包名为io.swagger.core.v3。

Swagger 3实现了OpenAPI 3接口规范，类似Hibernate实现JPA规范。Swagger 3提供了API注解，还提供了Swagger-ui用于生成API文档界面，以及其它的基础功能。

SpringDoc的作用主要是将Swagger 3和SpringBoot结合起来。

快速使用

只需要在pom.xml中引入SpringDoc即可。

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.11</version>
   </dependency>

启动程序后，访问/swagger-ui/index.html，就会显示API文档页面。

也可访问/v3/api-docs，返回的是API文档的JSON结构数据。可以用该数据生成其它风格的API文档页面，比如可以提供给Apifox生成API文档。

文档生成的原理是通过扫描源代码中的Controller，根据RequestMapping和相应方法的参数生成文档。

API注解

上面生成的文档并没有良好的注释，我们可以通过swagger-api注解，给接口加上注释。注解的包路径为io.swagger.v3.oas.annotations

@Tag(name = "ArticleController", description = "文章接口")
@RestController
public class ArticleController {
    @Operation(summary = "根据文章ID获取文章对象")
    @ApiResponses(value = {@ApiResponse(description = "文章对象")})
    @GetMapping("/article/{id}")
    public Article getArticleById(@Parameter(description = "文章ID", required = true) @PathVariable("id") Integer id) {
        ...
    }
}

类注释：@Tag(name = "ArticleController", description = "文章接口")
方法注释：@Operation(summary = "根据文章ID获取文章对象")
参数注释：@Parameter(description = "文章ID", required = true)
返回值: @ApiResponses(value = {@ApiResponse(description = "文章对象")})

OpenAPI规范

接口文档基于OpenAPI规范，了解OpenAPI规范有助于了解完整接口文档的编写方式。

参考资料：OpenAPI基本结构

上面的注解对应的OpenAPI规范大致如下：

paths:
  /article/{id}:
    get:
      summary: 根据文章ID获取文章对象
      parameters:
        - name: id
          in: path
          required: true
          description: 文章ID
          schema:
            type : integer
            format: int32
      responses:
        default:
          description: 文章对象

实体类注解

除了对API进行注解，还可对实体类进行注解。同时支持JSR-303注解。

@Schema(description = "文章")
@NotNull(message = "不能为空")
public class Article extends Serializable {
    @Schema(description = "标题")
    private String title;
}

文档定义

定义文档标题、文档版本号等信息。

@OpenAPIDefinition(
    info = @Info(
        title = "UJCMS API",
        description = "UJCMS 接口文档",
        version = "1.0.0"
    )
)
@Configuration
public class SwaggerConfig {
}

也可使用Java代码

@Bean
public OpenAPI openApi() {
    return new OpenAPI().info(new Info().title("UJCMS API").description("UJCMS 接口文档").version("1.0.0"));
}

对应的OpenAPI规范：

info:
  title: UJCMS API
  description: UJCMS 接口文档
  version: 1.0.0

文档分组

如果接口较多，可以对接口进行分组，方便查看。

@Configuration
public class SwaggerConfig {
    /**
     * 前台 API 分组
     */
    @Bean
    public GroupedOpenApi frontendGroup(@Value() {
        return GroupedOpenApi.builder().group("frontend").displayName("前台API")
                .addOpenApiCustomiser(openApi -> openApi.info(new Info().title("UJCMS 前台 API").version("1.0.0")))
                .packagesToScan("com.ujcms.cms.core.web.api")
                .pathsToMatch("/api/**")
                .build();
    }

    /**
     * 后台 API 分组
     */
    @Bean
    public GroupedOpenApi backendGroup() {
        return GroupedOpenApi.builder().group("backend").displayName("后台API")
                .addOpenApiCustomiser(openApi -> openApi.info(new Info().title("UJCMS 后台 API").version("1.0.0")))
                .packagesToScan("com.ujcms.cms.core.web.backendapi")
                .pathsToMatch("/api/backend/**")
                .build();
    }
}

也可在配置文件中设置分组：

springdoc.group-configs:
  - group: frontend
    displayName: 前台API
    packagesToScan: com.ujcms.cms.core.web.api
    pathsToMatch: /api/**
  - group: backend
    displayName: 后台API
    packagesToScan: com.ujcms.cms.core.web.backendapi
    pathsToMatch: /api/backend/**

权限认证

Swagger不仅能够查看文档，还能在线执行API，不仅能说还能练。

很多情况下API需要登录才能执行，这就需要权限认证。

以前面的后台API为例，增加权限认证的方式如下：


    private static final String BEARER_AUTH = "bearerAuth";

    @Bean
    public GroupedOpenApi backendGroup() {
        return GroupedOpenApi.builder().group("backend").displayName("后台API")
                .addOpenApiCustomiser(openApi -> openApi.info(new Info().title("UJCMS 后台 API").version("1.0.0")))
                .packagesToScan("com.ujcms.cms.core.web.backendapi")
                .pathsToMatch("/api/backend/**")
                .addOpenApiCustomiser(openApi -> openApi.components(new Components()
                        .addSecuritySchemes(BEARER_AUTH, new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"))))
                .addOperationCustomizer((operation, handlerMethod) -> {
                    operation.addSecurityItem(new SecurityRequirement().addList(BEARER_AUTH));
                    return operation;
                })
                .build();
    }

此时API接口文档处会出现Authorize按钮。