Springboot3 + knife4j(springdoc) 框架整合

news2024/11/27 16:30:45

前言

kinfe4j文档地址：https://doc.xiaominfo.com/docs/quick-start
springdoc文档地址：https://springdoc.org/#demos
原本使用的是springfox，自Springboot3开始，knife4j引入了springdoc。

Maven引入

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

Springfox转换Springdoc

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

@Api → @Tag 用于类,标识这个类是swagger的资源
@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden 用于类,方法,方法参数,表示这个方法或者类被忽略
@ApiImplicitParam → @Parameter 用于方法,表示单独的请求参数
@ApiImplicitParams → @Parameters 用于方法,包含多个请求参数
@ApiModel → @Schema 用于类 ,表示对类进行说明，用于参数用实体类接收
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY) 参数实体类某个参数不显示到接口文档中
@ApiModelProperty → @Schema 用于方法,字段,表示对model属性的说明或者数据操作更改
@ApiOperation(value = “foo”, notes = “bar”) → @Operation(summary = “foo”, description = “bar”) 用于方法,表示一个http请求的操作
@ApiParam → @Parameter 用于方法,参数,字段说明,表示对参数的添加元数据(说明或是否必填等)
@ApiResponse(code = 404, message = “foo”) → @ApiResponse(responseCode = “404”, description = “foo”) 用在@ApiResponses中，一般用于表达一个错误的响应信息

配置文件

一、单模块配置文件

@Configuration
public class SwaggerConfig {
  private Info createInfo(String title, String version){
      return new Info()
              .title(title)
              .version(version)
              .description("Knife4j集成springdoc-openapi示例")
              .termsOfService("http://条款网址")
              .license(
                      new License().name("Apache 2.0")
                      .url("http://doc.xiaominfo.com"));
  }

  @Bean
  public OpenAPI customOpenAPI() {
      return new OpenAPI()
              .info(createInfo("测试", "1.0.1"));
  }

}

效果：

二、多模块配置文件

@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi allOpenApi(@Value("${springdoc.version}") String appVersion) {
        String[] paths = {"/**"};
        return GroupedOpenApi.builder().group("总览")
        .addOpenApiCustomizer(openApi -> openApi.info(this.createInfo("后台管理系统API", appVersion)))
        .pathsToMatch(paths)
        .build();
    }

    @Bean
    public GroupedOpenApi sysOpenApi(@Value("${springdoc.version}") String appVersion) {
        String[] paths = {"/sys/**"};
        return GroupedOpenApi.builder().group("系统管理")
        .addOpenApiCustomizer(openApi -> openApi.info(this.createInfo("系统管理API", appVersion)))
        .pathsToMatch(paths)
        .build();
    }

    @Bean
    public GroupedOpenApi dataOpenApi(@Value("${springdoc.version}") String appVersion) {
        String[] paths = {"/data/**"};
        return GroupedOpenApi.builder().group("数据管理")
        .addOpenApiCustomizer(openApi -> openApi.info(this.createInfo("数据管理API", appVersion)))
        .pathsToMatch(paths)
        .build();
    }

    private Info createInfo(String title, String version){
        return new Info()
        .title(title)
        .version(version)
        .description("Knife4j集成springdoc-openapi示例")
        .termsOfService("http://条款网址")
        .license(
            new License().name("Apache 2.0")
            .url("http://doc.xiaominfo.com"));
    }

}