SpringBoot3 + OpenAPI3规范快速整合

原创已于 2024-10-16 11:42:10 修改 · 2.7k 阅读

19 ·

CC 4.0 BY-SA版权

文章标签：

#java #spring boot

于 2024-10-16 11:39:13 首次发布

工作总结专栏收录该内容

11 篇文章

订阅专栏

一、前言

相信大家在工作中都接触过 API 文档，市面上能生成和管理文档的工具有很多，比如 PostMan、ApiPost、ApiFox等等，当我们需要进行临时调试的时候实用工具确实很方便，但是实际开发项目中，集中管理API文档则需要额外的人力去维护，所以 swagger 诞生了，其实 swagger 本质是一种描述接口 API 的规范，目的是推动 API 的标准化，起初的版本为 swagger2， 2015 年，Swagger 规范由 Swagger 项目 捐赠给 Linux 基金会，并创建了 OpenAPI Initiative（OAI）。 Swagger 规范 被重命名为 OpenAPI 规范，而 Swagger 作为工具集的名称保留下来继续使用。因此，Swagger 2.0 规范的继承者就是 OpenAPI 3.0。

OpenAPI 3.0 是对 Swagger 2.0 的重大更新，规范的名称也从 Swagger 改为 OpenAPI。它在 Swagger 2.0 的基础上引入了许多改进和新的功能。也有人称其为 Swagger3

默认整合的接口文档页面比较简陋，我们选择第三方框架，对其做了一些增强扩展，UI 更符合使用习惯。

Knife4j 官方文档地址：https://doc.xiaominfo.com/

swagger 官方文档地址：https://swagger.io/docs/

springdoc-openapi 官方文档地址：https://springdoc.org/

springfox 3.0.0 官方整合案例参考(不建议使用，没找到详细文档，并且好久不维护了)：http://springfox.github.io/springfox/

二、快速开始

注意：

Spring Boot 3 只支持OpenAPI3规范
Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
JDK版本必须 >= 17

引入依赖

我们使用当前最新版本为 4.5.0

<properties>
    <knife4j.version>4.5.0</knife4j.version> <!-- knife4j 接口文档 -->
</properties>

<!-- knife4j swagger3 接口文档 -->
<dependencies>
  <dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
  </dependency>
</dependencies>

修改配置文件

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.yang.itshare.controller # 扫描接口所在的包
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

使用 OpenAPI3 的规范注解，注释各个接口，以下是示例代码，包含了常用的注解，可以参照修改

@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {

    @Operation(summary = "普通body请求")
    @PostMapping("/body")
    public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){
        return ResponseEntity.ok(fileResp);
    }

    @Operation(summary = "普通body请求+Param+Header+Path")
    @Parameters({
        @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
        @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
        @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
    })
    @PostMapping("/bodyParamHeaderPath/{id}")
    public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){
        fileResp.setName(fileResp.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);
        return ResponseEntity.ok(fileResp);
    }
}

最后，访问Knife4j的文档地址：http://ip:port/doc.html 即可查看文档

三、定制化需求

可以看到，文档的一些基础信息，我们并没有指定，使用的都是默认的，当然这些对应接口的使用并不重要，但是为了规范，我们最好还是配置一下。

knife4j 只是对于 springdoc-openapi 做了一些增强，所有配置可以参考原项目说明 https://springdoc.org/#properties

增强配置：https://doc.xiaominfo.com/docs/features/enhance

我这里只列出基础的配置：

# knife4j的增强配置，不需要增强可以不配
knife4j:
  # 开启增强配置
  enable: true
  # 开启生产环境屏蔽
  production: false
  setting:
    language: zh_cn
    swagger-model-name: 实体类列表
    enable-version: true # 是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
    enable-host-text: 127.0.0.1:8080
    enable-footer-custom: true
    footer-custom-content: Apache License 2.0 | Copyright  2024-[itshare](https://www.csyblog.cn)

然后是作者信息，版本信息，这个没有找到具体的 yaml 配置项，但是可以通过 bean 的方式注入一个配置对象。

参考文档：https://springdoc.org/#migrating-from-springdoc-v1

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        // 建造者模式构建Docket
        return GroupedOpenApi.builder()
        .addOpenApiCustomizer(openApi -> openApi.setInfo(apiInfo()))
        .group("ITSHARE")
        // 需要放出的接口
        .packagesToScan("com.yang.itshare.controller")
        .build();
    }

    private Info apiInfo() {
        return new Info()
        .title("接口文档")
        .description("ITSHARE API描述")
        .contact(new Contact().url("https://www.csyblog.cn").name("申阳").email("2417254000@qq.com"))
        .license(new License().name("Apache License 2.0").identifier("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0"))
        .version("v1.0");
    }