SpringBoot3中Swagger整合knife4j和springdoc的配置说明

springboot3开始javax包改成了jakarta，而swagger-oas等包中依然使用的是javax所以报错。另外springfox已经过时了，两年没更新了，并且不支持OpenAPI3 标准，而SpringBoot3只支持OpenAPI3规范，所以要迁移到springdoc

Knife4J是一款基于Swagger快速生成API文档和调试平台的开源工具，它可以轻松地将Swagger规范转换成易于阅读的文档，并支持在线测试API。Knife4J内置了多种主题和插件，提供了丰富的样式和功能配置，可以自定义API文档的展示方式和内容。

OpenAPI3的规范，目前针对Java的Spring Boot项目，主要支持的有2个版本

• springfox 3.0.0： 同时兼容OpenAPI2以及OpenAPI3，但是停更很久了
• springdoc-openapi：兼容OpenAPI3规范，更新速度频繁

Knife4j在只有的OpenAPI3规范中，底层基础框架选择springdoc-openapi项目

• 针对Springfox3.0.0版本会放弃。

Spring Boot版本兼容性

以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐：
Spring Boot版本Knife4j Swagger2规范Knife4j OpenAPI3规范1.5.x2.0.0<Knife4j 2.0.0>=Knife4j 4.0.02.02.2Knife4j 2.0.0 ~ 2.0.6>=Knife4j 4.0.02.2.x2.4.0Knife4j 2.0.6 ~ 2.0.9>=Knife4j 4.0.02.4.02.7.x>=Knife4j 4.0.0>=Knife4j 4.0.0>= 3.0>=Knife4j 4.0.0>=Knife4j 4.0.0

参考：knife4j官网 springdoc-openapi官网

配置： JDK17 + SpringBoot：3.1.5 + knife4j：4.3.0 + springdoc2.2.0

1.导入依赖（SpringBoot3）

<!--基于knife4j-openapi3的api接口文档生成--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version></dependency>

2.在application.yml中设置相关配置：

#springdoc相关配置
springdoc:
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/swagger-ui.html会自动重定向到swagger页面
    path:/swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path:/v3/api-docs    #swagger后端请求地址
    enabled:true   #是否开启文档功能
  group-configs:- group: 'com.hgh.yuzhan'
      paths-to-match:'/**'
      packages-to-scan: com.hgh.yuzhan    #按包路径匹配:一般到启动类的包名

#knife4j相关配置 可以不用改
knife4j:
  enable:true    #开启knife4j，无需添加@EnableKnife4j注解
  setting:
    language: zh_cn   #中文
    swagger-model-name: 实体类   #重命名SwaggerModel名称,默认
  #开启Swagger的Basic认证功能,默认是false
  basic:
    enable:true
    # Basic认证用户名
    username: hgh
    # Basic认证密码
    password: a1234567

3.配置文件

/**
 * @description: knife4j配置类
 * @authod:  GreyPigeon mail:[email protected]
 * @date:    2023/11/10 20:49
 **/@ConfigurationpublicclassOpenApiConfig{@BeanpublicOpenAPIspringShopOpenAPI(){returnnewOpenAPI()// 接口文档标题.info(newInfo().title("愈站API接口文档")// 接口文档简介.description("这是基于Knife4j OpenApi3的接口文档")// 接口文档版本.version("v1.0")// 开发者联系方式.contact(newContact().name("GrayPigeonHGH").email("[email protected]"))).externalDocs(newExternalDocumentation().description("SpringBoot基础框架").url("http://127.0.0.1:8088"));}//以下分组可省略@BeanpublicGroupedOpenApisystemApi(){returnGroupedOpenApi.builder().group("System系统模块").pathsToMatch("/system/**").build();}@BeanpublicGroupedOpenApiauthApi(){returnGroupedOpenApi.builder().group("Auth权限模块").pathsToMatch("/captcha","/login").build();}}

参考：https://huaweicloud.csdn.net/63876baddacf622b8df8bb31.html

• 注意：Knife4j 自4.0版本，下面的配置在knife4j-openapi2-spring-boot-starter中仍然需要如此配置，而在knife4j-openapi3-spring-boot-starter和knife4j-openapi3-jakarta-spring-boot-starter则不需要以下配置！！！

@Configuration@EnableSwagger2WebMvcpublicclassSwaggerConfiguration{/*引入Knife4j提供的扩展类*/privatefinalOpenApiExtensionResolver openApiExtensionResolver;@AutowiredpublicSwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver){this.openApiExtensionResolver = openApiExtensionResolver;}@Bean(value ="defaultApi2")publicDocketdefaultApi2(){String groupName="2.X版本";Docket docket=newDocket(DocumentationType.SWAGGER_2).host("https://www.baidu.com").apiInfo(apiInfo()).groupName(groupName).select().apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2")).paths(PathSelectors.any()).build()//赋予插件体系.extensions(openApiExtensionResolver.buildExtensions(groupName));return docket;}

4.访问路径

swagger

接口文档默认地址：http://localhost:8080/swagger-ui.html#

Knife4j

接口文档默认地址：http://127.0.0.1:8080/doc.html

5. Springfox改用Springdoc后，注解改变：

@Api → @Tag@ApiIgnore → @Parameter(hidden =true) or @Operation(hidden =true) or @Hidden@ApiImplicitParam → @Parameter@ApiImplicitParams → @Parameters@ApiModel → @Schema@ApiModelProperty(hidden =true) → @Schema(accessMode =READ_ONLY)@ApiModelProperty → @Schema@ApiOperation(value ="foo", notes ="bar") → @Operation(summary ="foo", description ="bar")@ApiParam → @Parameter@ApiResponse(code =404, message ="foo") → @ApiResponse(responseCode ="404", description ="foo")

6.以下举几个简单的例子：

6.1 Controller：

@Tag(name ="用户接口")@RestController@RequestMapping("sys/user")publicclassSysUserController{@ResourceprivateISysUserService sysUserService;@Operation(summary ="分页查询")@GetMapping("page")publicAjaxResultqueryPage(@ParameterObjectSysUserPageDTO dto){PageInfo page = sysUserService.queryPage(dto);returnAjaxResult.success(page);}@Operation(summary ="详情")@GetMapping("{id}")publicAjaxResultqueryInfo(@PathVariableLong id){SysUserDTO dto = sysUserService.queryById(id);returnAjaxResult.success(dto);}@Operation(summary ="新增")@PostMappingpublicAjaxResultsave(@RequestBodySysUserDTO dto){Long id = sysUserService.saveInfo(dto);returnAjaxResult.success(id);}}

6.2 实体类

@Getter@Setter@TableName("user")@Schema(name ="User", description ="$!{table.comment}")publicclassUserimplementsSerializable{privatestaticfinallong serialVersionUID =1L;@Schema(description ="主键")@TableId("id")privateLong id;@Schema(description ="用户名")@TableField("name")privateString name;@Schema(description ="手机号")@TableField("phone")privateString phone;@Schema(description ="性别")@TableField("sex")privateString sex;@Schema(description ="状态 0:禁用，1:正常")@TableField("status")privateInteger status;}