集成 Spring Doc 接口文档和 knife4j-SpringBoot 2.7.2 实战基础 ...

优雅哥 SpringBoot 2.7.2 实战基础 - 04 -集成 Spring Doc 接口文档和 knife4j

前面已经集成 MyBatis Plus、Druid 数据源，开发了 5 个接口。在测试这 5 个接口时使用了 HTTP Client 或 PostMan，无论是啥都比较麻烦：得自己写请求地址 URL、请求参数等，于是多年前就出现了 Swagger 这个玩意。Swagger 可以自动生成接口文档，还能很方便的测试各个接口。但不幸的是，MVN Repository 上面 Springfox Swagger2 的版本停止于 2020 年 7月，而写下这篇文章是 2022 年 8 月，已经两年过去没有动静了，与此同时，springdoc-openapi 悄然出现。
spring doc open api 支持 Open API 3、Swagger-ui等，可以很方便与 Spring Boot 整合，配置和使用与 Springfox Swagger2 类似。
1 集成 Spring Doc

1.1 添加依赖

springdoc-openapi 不是 Spring Framework 官方团队开发的，而是社区项目，没有包含在 spring-boot-dependencies  中。故需要先定义版本号：

1. <properties>
2.                 ....
3.     <springdoc-openapi-ui.version>1.6.9</springdoc-openapi-ui.version>
4. </properties>

复制代码

添加依赖：

1. <dependency>
2.     <groupId>org.springdoc</groupId>
3.     <artifactId>springdoc-openapi-ui</artifactId>
4.     <version>${springdoc-openapi-ui.version}</version>
5. </dependency>

复制代码

该依赖里面使用了 swagger-ui，以HTML形式展示文档。
1.2 编写配置类

其实配置类写不写都可以，如果不写配置类，就通过注解定义文档信息就可以。创建类：com.yygnb.demo.config.SpringDocConfig

1. package com.yygnb.demo.config;
3. import io.swagger.v3.oas.models.ExternalDocumentation;
4. import io.swagger.v3.oas.models.OpenAPI;
5. import io.swagger.v3.oas.models.info.Info;
6. import org.springframework.context.annotation.Bean;
7. import org.springframework.context.annotation.Configuration;
9. @Configuration
10. public class SpringDocConfig {
12.     private String title = "Hero SpringBoot Demo";
13.     private String description = "Hero Demo for usage of Spring Boot";
14.     private String version = "v0.0.1";
15.     private String websiteName = "Hero Website";
16.     private String websiteUrl = "http://www.yygnb.com";
18.     @Bean
19.     public OpenAPI heroOpenAPI() {
20.         return new OpenAPI()
21.                 .info(new Info().title(title)
22.                         .description(description)
23.                         .version(version))
24.                 .externalDocs(new ExternalDocumentation().description(websiteName)
25.                         .url(websiteUrl));
26.     }
27. }

复制代码

上面的配置定义了展示的文档的信息，与界面上对应关系如下：

在配置文件中除了可以配置文档的信息，还可以配置文档分组、Authorization 等，在后面的企业级实战文章中会具体描写，将会在网关层 spring cloud gateway 中集成所有微服务的接口。
1.3 配置yml

在 application.yml 配置 springdoc：

1. # 接口文档
2. springdoc:
3.   packages-to-scan: com.yygnb.demo.controller
4.   swagger-ui:
5.     enabled: true

复制代码

这两项不配置也可以，packages-to-scan 默认为启动类所在的路径；springdoc.swagger-ui.enabled 默认为true，配置后可以在不同的环境中开启或关闭。
1.4 添加注解

springdoc-openapi 与 springfox-swagger2 提供的注解有很大差别：
swagger 2spring doc描述@Api@Tag修饰 controller 类，类的说明@ApiOperation@Operation修饰 controller 中的接口方法，接口的说明@ApiModel@Schema修饰实体类，该实体的说明@ApiModelProperty@Schema修饰实体类的属性，实体类中属性的说明@ApiImplicitParams@Parameters接口参数集合@ApiImplicitParam@Parameter接口参数@ApiParam@Parameter接口参数修改实体类 Computer，添加 springdoc-openapi 注解：

1. @Schema(title = "电脑")
2. @Data
3. @NoArgsConstructor
4. @AllArgsConstructor
5. @Builder
6. public class Computer implements Serializable {
8.     private static final long serialVersionUID = 1L;
10.     @TableId(value = "id", type = IdType.AUTO)
11.     private Long id;
13.     @Schema(title = "尺寸")
14.     private BigDecimal size;
16.     @Schema(title = "操作系统")
17.     private String operation;
19.     @Schema(title = "年份")
20.     private String year;
21. }

复制代码

修改控制器 ComputerController，添加注解：

1. @Tag(name = "电脑相关接口")
2. @RequiredArgsConstructor
3. @RestController
4. @RequestMapping("/computer")
5. public class ComputerController {
7.     private final IComputerService computerService;
9.     @Operation(summary = "根据id查询电脑")
10.     @GetMapping("/{id}")
11.     public Computer findById(
12.             @Parameter(name = "id", required = true, description = "电脑id") @PathVariable Long id) {
13.         return this.computerService.getById(id);
14.     }
16.     @Operation(summary = "分页查询电脑列表")
17.     @Parameters(value = {
18.             @Parameter(name = "page", description = "页面，从1开始", example = "2"),
19.             @Parameter(name = "size", description = "每页大小", example = "10")
20.     })
21.     @GetMapping("/find-page/{page}/{size}")
22.     public Page<Computer> findPage(@PathVariable Integer page, @PathVariable Integer size) {
23.         return this.computerService.page(new Page<>(page, size));
24.     }
26.     @Operation(summary = "新增电脑")
27.     @PostMapping()
28.     public Computer save(@RequestBody Computer computer) {
29.         computer.setId(null);
30.         this.computerService.save(computer);
31.         return computer;
32.     }
34.     @Operation(summary = "根据id修改电脑")
35.     @PutMapping("/{id}")
36.     public Computer update(
37.             @Parameter(name = "id", required = true, description = "电脑id") @PathVariable Long id,
38.             @RequestBody Computer computer) {
39.         computer.setId(id);
40.         this.computerService.updateById(computer);
41.         return computer;
42.     }
44.     @Operation(summary = "根据id删除电脑")
45.     @DeleteMapping("/{id}")
46.     @Parameter(name = "id", required = true, description = "电脑id")
47.     public void delete(@PathVariable Long id) {
48.         this.computerService.removeById(id);
49.     }
50. }

复制代码

1.5 运行测试

启动服务，在浏览器中访问：

1. http://localhost:9099/swagger-ui/index.html

复制代码

2 api-docs

在文档标题下面有一个小链接：/v3/api-docs，点击该链接，会在新页面中显示一大坨 JSON 数据。

看似很无聊的数据，却有着重大意义，swagger-ui 就是通过这些数据渲染出页面的。此外，这些JSON数据在某种程度上可以简化前端的开发及前后端网络请求的工作量。
hero-admin-ui

优雅哥正在开发的基于 Vue 3 + TypeScript 的开源项目 hero-admin-ui，其特色就是基于 JSON Schema 的表单和列表。通过 JSON Schema 可以快速渲染出一个列表、表单，甚至是搜索页和详情表单页。如果独立使用 hero-admin-ui，需要手动编写 JSON Schema，但如果后端接口整合了 Swagger 或 Spring Doc，上面 api-docs 返回的 JSON，就包含了 JSON Schema，二者结合可以快速实现搜索页、表单页等。目前 hero-admin-ui 已发布在 npmjs 上，也已经提交到 github上，大家可以搜索关键字 hero-admin-ui 查看。在后面的实战篇中，前端部分将会使用这个组件库实现前端页面。

3 自定义配置

在 ”1.2 编写配置类“ 一节，文档信息都是写死在代码中的，如果多个微服务都要集成 spring doc，可以把前面写的 SpringDocConfig 提取到公共模块中，通过maven 依赖引用，在 application.yml 中配置不同的变量。
3.1 添加依赖

1. <dependency>
2.     <groupId>org.springframework.boot</groupId>
3.     <artifactId>spring-boot-configuration-processor</artifactId>
4.     <optional>true</optional>
5. </dependency>

复制代码

配置该依赖的目的是在编写 application.yml 时，自定义的属性有代码提示。它会生成配置元数据，无需自己手动编写。
3.2 定义配置的实体类

创建 com.yygnb.demo.config.DocInfo，将 SpringDocConfig 中写死的属性都移到这个配置实体类中：

1. @Data
2. @Component
3. @ConfigurationProperties(prefix = "doc-info")
4. public class DocInfo {
6.     private String title = "Demo Title";
7.     private String description = "Demo Description";
8.     private String version = "v0.0.1";
9.     private String websiteName = "Demo Website";
10.     private String websiteUrl = "http://www.yygnb.com";
11. }

复制代码

注解 @ConfigurationProperties(prefix = "doc-info") 声明配置属性，在 application.yml 配置时就可以使用 doc-info。
3.3 重构 SpringDocConfig

在 SpringDocConfig 中引入 DocInfo，并通过构造函数进行注入：

1. @RequiredArgsConstructor
2. @Configuration
3. public class SpringDocConfig {
5.     private final DocInfo docInfo;
7.     @Bean
8.     public OpenAPI springShopOpenAPI() {
9.         return new OpenAPI()
10.                 .info(new Info().title(docInfo.getTitle())
11.                         .description(docInfo.getDescription())
12.                         .version(docInfo.getVersion()))
13.                 .externalDocs(new ExternalDocumentation().description(docInfo.getWebsiteName())
14.                         .url(docInfo.getWebsiteUrl()));
15.     }
16. }

复制代码

补充一个小点：注解 @RequiredArgsConstructor 是 lombok 中提供的，它等价于在类中编写了方法：

1. public SpringDocConfig(DocInfo docInfo) {
2.     this.docInfo = docInfo;
3. }

复制代码

构造注入时，在构造函数中写大量的属性，毫无意义。既然已经使用了 @Data 注解，为啥不用 @RequiredArgsConstructor 呢？
3.4 使用自定义配置

自定义配置已经完成，可以在 application.yml 中使用 DocInfo 对应的配置了：

1. doc-info:
2.   title: SpringBoot Demo演示
3.   description: 学习 Spring Boot 2.7.2

复制代码

DocInfo 所有属性都定义了默认值，在 application.yml 可以覆盖默认值，如上面的 title 和 description 属性。重启服务查看运行效果：

4 集成 knife4j

在之前 springfox-swagger 的时代，很多同学不喜欢 swagger-ui 的界面风格，会集成 knife4j 的 ui。Spring Doc 也可以集成 knife4j。
如果要使用 knife4j ，Spring Doc 的配置中需要添加分组配置，我们这里添加一个最简单的分组配置。
com.yygnb.demo.config.SpringDocConfig

1. @RequiredArgsConstructor
2. @Configuration
3. public class SpringDocConfig {
5.     private final DocInfo docInfo;
7.     @Bean
8.     public OpenAPI heroOpenAPI() {
9.         return new OpenAPI()
10.                 .info(new Info().title(docInfo.getTitle())
11.                         .description(docInfo.getDescription())
12.                         .version(docInfo.getVersion()))
13.                 .externalDocs(new ExternalDocumentation().description(docInfo.getWebsiteName())
14.                         .url(docInfo.getWebsiteUrl()));
15.     }
17.     @Bean
18.     public GroupedOpenApi publicApi() {
19.         return GroupedOpenApi.builder()
20.                 .group(docInfo.getTitle())
21.                 .pathsToMatch("/**")
22.                 .build();
23.     }
24. }

复制代码

如果不添加这个 GroupedOpenApi 实例，knife4j ui就显示不出来。
在 pom.xml 中引入 knife4j

1. <properties>
2. ...
3.     <knife4j-springdoc-ui.version>3.0.3</knife4j-springdoc-ui.version>
4. </properties>
6. <dependencies>
7. ...
8.     <dependency>
9.         <groupId>com.github.xiaoymin</groupId>
10.         <artifactId>knife4j-springdoc-ui</artifactId>
11.         <version>${knife4j-springdoc-ui.version}</version>
12.     </dependency>
13. </dependencies>

复制代码

启动服务，访问：

1. http://localhost:9099/doc.html

复制代码

显示 knife4j 的ui：


今日优雅哥（工\/youyacoder）学习结束，期待关注留言分享~~

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！