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

03-03 9057阅读 0评论

 

SpringBoot3中Swagger整合knife4j和springdoc的配置说明 第1张
（图片来源网络，侵删）

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.x~2.0.0=Knife4j 4.0.0
      2.0~2.2Knife4j 2.0.0 ~ 2.0.6>=Knife4j 4.0.0
      2.2.x~2.4.0Knife4j 2.0.6 ~ 2.0.9>=Knife4j 4.0.0
      2.4.0~2.7.x>=Knife4j 4.0.0>=Knife4j 4.0.0
      >= 3.0>=Knife4j 4.0.0>=Knife4j 4.0.0

      参考：knife4j官网 springdoc-openapi官网

      SpringBoot3中Swagger整合knife4j和springdoc的配置说明 第2张
      （图片来源网络，侵删）
      配置： JDK17 + SpringBoot：3.1.5 + knife4j：4.3.0 + springdoc2.2.0

       

      1.导入依赖（SpringBoot3）
       

    com.github.xiaoymin
    knife4j-openapi3-jakarta-spring-boot-starter
    4.3.0
      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:2371849349@qq.com
 * @date:    2023/11/10 20:49
 **/
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                // 接口文档标题
                .info(new Info().title("愈站API接口文档")
                        // 接口文档简介
                        .description("这是基于Knife4j OpenApi3的接口文档")
                        // 接口文档版本
                        .version("v1.0")
                        // 开发者联系方式
                        .contact(new Contact().name("GrayPigeonHGH").email("2371849349@qq.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringBoot基础框架")
                        .url("http://127.0.0.1:8088"));
    }
    //以下分组可省略
    @Bean
    public GroupedOpenApi systemApi() {
        return GroupedOpenApi.builder().group("System系统模块")
                .pathsToMatch("/system/**")
                .build();
    }
    @Bean
    public GroupedOpenApi authApi() {
        return GroupedOpenApi.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
@EnableSwagger2WebMvc
public class SwaggerConfiguration {
    /*引入Knife4j提供的扩展类*/
   private final OpenApiExtensionResolver openApiExtensionResolver;
    @Autowired
    public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }
@Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        String groupName="2.X版本";
        Docket docket=new Docket(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")
public class SysUserController {
    @Resource
    private ISysUserService sysUserService;
    @Operation(summary = "分页查询")
    @GetMapping("page")
    public AjaxResult queryPage(@ParameterObject SysUserPageDTO dto) {
        PageInfo page = sysUserService.queryPage(dto);
        return AjaxResult.success(page);
    }
    @Operation(summary = "详情")
    @GetMapping("{id}")
    public AjaxResult queryInfo(@PathVariable Long id) {
        SysUserDTO dto = sysUserService.queryById(id);
        return AjaxResult.success(dto);
    }
    @Operation(summary = "新增")
    @PostMapping
    public AjaxResult save(@RequestBody SysUserDTO dto) {
        Long id = sysUserService.saveInfo(dto);
        return AjaxResult.success(id);
    }
}
        6.2 实体类
        @Getter
@Setter
@TableName("user")
@Schema(name = "User", description = "$!{table.comment}")
public class User implements Serializable {
    private static final long serialVersionUID = 1L;
    @Schema(description = "主键")
    @TableId("id")
    private Long id;
    @Schema(description = "用户名")
    @TableField("name")
    private String name;
    @Schema(description = "手机号")
    @TableField("phone")
    private String phone;
    @Schema(description = "性别")
    @TableField("sex")
    private String sex;
    @Schema(description = "状态 0:禁用，1:正常")
    @TableField("status")
    private Integer status;
}

相关阅读：

1、IK分词器和ElasticSearch集成使用

2、网络空间搜索引擎- FOFA的使用技巧总结

3、YOLOv8目标检测：使用ONNX模型进行推理

4、Java进阶-Java Stream API详解与使用

5、Edge的使用心得与深度探索

免责声明
1、本网站属于个人的非赢利性网站，转载的文章遵循原作者的版权声明。
2、本网站转载文章仅为传播更多信息之目的，凡在本网站出现的信息，均仅供参考。本网站将尽力确保所
提供信息的准确性及可靠性，但不保证信息的正确性和完整性，且不对因信息的不正确或遗漏导致的任何
损失或损害承担责任。
3、任何透过本网站网页而链接及得到的资讯、产品及服务，本网站概不负责，亦不负任何法律责任。
4、本网站所刊发、转载的文章，其版权均归原作者所有，如其他媒体、网站或个人从本网下载使用，请在
转载有关文章时务必尊重该文章的著作权，保留本网注明的“稿件来源”，并白负版权等法律责任。

手机扫描二维码访问

文章版权声明：除非注明，否则均为主机测评原创文章，转载或复制请以超链接形式并注明出处。

相关阅读

发表评论

快捷回复： 表情：
评论列表 （暂无评论，9057人围观）

还没有评论，来说两句吧...

目录[+]