springboot3整合swagger3.0之knife4j-openapi3

于 2024-10-09 14:50:49 发布
阅读量1.1k 收藏 14
点赞数 20
分类专栏： swagger3 knife4j springboot3 文章标签： swagger3 knife4j
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_29278623/article/details/142785348
版权
swagger3 同时被 3 个专栏收录
1 篇文章 0 订阅
订阅专栏
knife4j
1 篇文章 0 订阅
订阅专栏
springboot3
1 篇文章 0 订阅
订阅专栏

1、依赖的引入

  • 首先是我的springboot的版本号
<parent>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-parent</artifactId>
   <version>3.3.0</version>
   <relativePath/> <!-- lookup parent from repository -->
</parent>
  •  然后是 knife4j-openapi3-jakarta-spring-boot-starter的版本号
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

2、yml文件的配置

  • 以下是基础配置
# 配置springdoc-openapi，用于文档化和访问API
springdoc:
  # 配置Swagger UI的访问路径和排序方式
  swagger-ui:
    path: /swagger-ui.html  # Swagger UI的访问路径
    tags-sorter: alpha      # 按字母顺序排序标签
    operations-sorter: alpha  # 按字母顺序排序操作
  # 配置API文档的访问路径
  api-docs:
    path: /v3/api-docs  # API文档的访问路径
  # 配置API分组，用于组织和管理API
  group-configs:
    - group: 'default'   # API分组名称
      paths-to-match: '/**'  # 匹配所有路径
      packages-to-scan: net.xxxx.demo.controller  # 扫描的包，用于自动发现API

# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
  • 下面是详细的配置
  • 注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启
# 配置Knife4j，以启用Swagger文档的增强功能和定制化展示
knife4j:
  # 启用Knife4j扩展
  enable: true
  # 配置展示的文档分组
  documents:
    - 
      # 文档分组标题
      group: 2.X版本
      # 文档分组描述
      name: 接口签名
      # 指定接口文档的位置
      locations: classpath:sign/*
  # 配置Knife4j的展示细节和功能开关
  setting:
    # 设置界面语言
    language: zh-CN
    # 启用Swagger模型展示
    enable-swagger-models: true
    # 启用文档管理功能
    enable-document-manage: true
    # 设置Swagger模型的显示名称
    swagger-model-name: 实体类列表
    # 是否显示版本信息
    enable-version: false
    # 是否启用参数缓存刷新
    enable-reload-cache-parameter: false
    # 启用后端脚本支持
    enable-after-script: true
    # 过滤特定方法类型的multipart/form-data接口
    enable-filter-multipart-api-method-type: POST
    # 是否过滤所有multipart/form-data类型的接口
    enable-filter-multipart-apis: false
    # 启用请求缓存
    enable-request-cache: true
    # 是否显示自定义主机名
    enable-host: false
    # 设置自定义的主机名
    enable-host-text: 192.168.0.193:8000
    # 启用自定义首页
    enable-home-custom: true
    # 设置自定义首页的路径
    home-custom-path: classpath:markdown/home.md
    # 是否启用搜索功能
    enable-search: false
    # 是否显示页脚
    enable-footer: false
    # 启用自定义页脚内容
    enable-footer-custom: true
    # 设置自定义页脚的内容
    footer-custom-content: Apache License 2.0
    # 是否启用动态参数
    enable-dynamic-parameter: false
    # 启用调试模式
    enable-debug: true
    # 启用OpenAPI 3.0的支持
    enable-open-api: false
    # 启用接口分组功能
    enable-group: true
  # 是否启用CORS跨域支持
  cors: false
  # 是否启用生产模式
  production: false
  # 配置基本的认证信息
  basic:
    # 启用基本认证
    enable: false
    # 设置用户名
    username: test
    # 设置密码
    password: 12313
  • 各个配置说明见下表格
属性默认值说明值
knife4j.enableFALSE是否开启Knife4j增强模式
knife4j.corsFALSE是否开启一个默认的跨域配置,该功能配合自定义Host使用
knife4j.productionFALSE是否开启生产环境保护策略,详情参考文档
knife4j.basic对Knife4j提供的资源提供BasicHttp校验,保护文档
knife4j.basic.enableFALSE关闭BasicHttp功能
knife4j.basic.usernamebasic用户名
knife4j.basic.passwordbasic密码
knife4j.documents自定义文档集合，该属性是数组
knife4j.documents.group所属分组
knife4j.documents.name类似于接口中的tag,对于自定义文档的分组
knife4j.documents.locationsmarkdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)
knife4j.setting前端Ui的个性化配置属性
knife4j.setting.enable-after-scriptTRUE调试Tab是否显示AfterScript功能,默认开启
knife4j.setting.languagezh-CNUi默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
knife4j.setting.enable-swagger-modelsTRUE是否显示界面中SwaggerModel功能
knife4j.setting.swagger-model-nameSwagger Models重命名SwaggerModel名称,默认
knife4j.setting.enable-document-manageTRUE是否显示界面中"文档管理"功能
knife4j.setting.enable-reload-cache-parameterFALSE是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
knife4j.setting.enable-versionFALSE是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
knife4j.setting.enable-request-cacheTRUE是否开启请求参数缓存
knife4j.setting.enable-filter-multipart-apisFALSE

针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,

如果开启此配置,默认展示一个Post类型的接口地址

knife4j.setting.enable-filter-multipart-api-method-typePOST具体接口的过滤类型
knife4j.setting.enable-hostFALSE是否启用Host
knife4j.setting.enable-host-textFALSEHOST地址
knife4j.setting.enable-home-customFALSE是否开启自定义主页内容
knife4j.setting.home-custom-path主页内容Markdown文件路径
knife4j.setting.enable-searchFALSE是否禁用Ui界面中的搜索框
knife4j.setting.enable-footerTRUE是否显示Footer
knife4j.setting.enable-footer-customFALSE是否开启自定义Footer
knife4j.setting.footer-custom-contentFALSE自定义Footer内容
knife4j.setting.enable-dynamic-parameterFALSE是否开启动态参数调试功能
knife4j.setting.enable-debugTRUE启用调试
knife4j.setting.enable-open-apiTRUE显示OpenAPI规范
knife4j.setting.enable-groupTRUE显示服务分组

 

3、接口注解

1、@Operation
  • summary：简短描述。
  • description：详细说明。
  • tags：标签，用于分类API。
  • responses：响应描述。
@Operation(summary = "获取科室列表", description = "返回所有科室的列表")
@GetMapping("/depts")
public List<Dept> getDepts() {
    // ...
}

2、@Tag

  • name：标签名。
  • description：标签描述。
@Tag(name = "科室管理API", description = "科室相关操作")
@RestController
@RequestMapping("/depts")
public class deptController {
    // ...
}
3、@ApiResponses     
  • responseCode：HTTP状态码。
  • description：描述信息。
  • content：响应内容类型和模式。
@Operation(summary = "获取科室列表")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", 
schema = @Schema(implementation = Dept.class))),
    @ApiResponse(responseCode = "400", description = "请求参数错误"),
    @ApiResponse(responseCode = "404", description = "找不到资源"),
    @ApiResponse(responseCode = "500", description = "服务器内部错误")
})
@GetMapping("/depts")
public List<Dept> getDepts() {
    // ...
}

4、@Parameter

  • name：参数名。
  • description：参数描述。
  • required：是否必须参数。
  • schema：参数模式
@Operation(summary = "获取科室详情")
@GetMapping("/{id}")
public User getDept(@Parameter(description = "科室ID", required = true) @PathVariable Long id) {
    // ...
}

5、@Schema

  • description：字段描述。
  • example：示例值。
  • required：是否必须字段。
  • type：字段类型。
@Schema(description = "科室实体")
public class Dept {
    
    @Schema(description = "科室ID", example = "1")
    private Long id;

    @Schema(description = "科室名", example = "肿瘤科")
    private String name;

    // getters and setters
}

6、@ArraySchema

  • schema：数组元素的模式。
  • description：数组描述。
@Schema(description = "科室列表")
public class DeptListResponse {

    @ArraySchema(schema = @Schema(implementation = Dept.class), description = "科室数组")
    private List<Dept> depts;

    // getters and setters
}

4、swagger的java配置

package net.xxx.xxx.common.config.swagger;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

/**
 * Swagger 配置
 * <p>
 * Spring Doc FAQ: https://springdoc.org/#faq
 *
 * @author weiyang.shi
 * @date 2099/12/12
 */
@Configuration
public class SwaggerConfig {

    private static final String TOKEN_HEADER = "Authorization";

    /**
     * 接口信息
     */
    @Bean
    public OpenAPI apiInfo() {
        return new OpenAPI()
                .components(
                        new Components().addSecuritySchemes(TOKEN_HEADER,
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.APIKEY)
                                        // 这里配置 bearer 后，你的请求里会自动在 token 前加上 Bearer
                                        .scheme("bearer")
                                        .bearerFormat("JWT")
                        ).addParameters(TOKEN_HEADER,
                                new Parameter()
                                        .in("header")
                                        .schema(new StringSchema())
                                        .name(TOKEN_HEADER)
                        ))
                .info(new Info()
                        .title("XXX项目接口文档")
                        .version("1.0.0")
                        .description("XXX项目接口文档")
                        .license(new License().name("Apache 2.0")
                                .url("https://www.baidu.tech"))
                )// 引入外部的文档，我这里引得是 springdoc 官方文档地址，你可以不配此项
                .externalDocs(new ExternalDocumentation()
                        .description("SpringDoc Full Documentation")
                        .url("https://springdoc.org/")
                );
    }

    /**
     * 接口分组-测试接口
     *
     * @return
     */
    @Bean
    public GroupedOpenApi testOpenApi() {
        String[] paths = {"/**"};

        String packagesToScan[] = {"net.xxx.xxx.controller.test"};
        return GroupedOpenApi.builder()
                .group("测试接口")
                .packagesToScan(packagesToScan)
                .pathsToMatch(paths)
                .build();
    }

     /**
     * 接口分组-通用接口
     *
     * @return
     */
    @Bean
    public GroupedOpenApi comatOpenApi() {
        String[] paths = {"/**"};

        String packagesToScan[] = {"net.xxx.xxx.controller.comat"};
        return GroupedOpenApi.builder()
                .group("通用接口")
                .packagesToScan(packagesToScan)
                .pathsToMatch(paths)
                .build();
    }



}

5、访问地址

http://localhost:8080/doc.html

施小楠
关注
专栏目录
springboot3整合knife4j详细版，包会！（不带swagger2玩）
qq_51774011的博客
07-21 4143
springboot3在整合swagger2或者3时均不太好使，而且swagger的默认ui页面真的一言难尽，官方现在推荐使用springdoc-openapi集成接口文档，但是经过测试一些注解个性化文档时存在不好使的情况，而且ui界面依然感觉不好看。本文详细记录了knife4j集成接口文档的详细使用步骤，配置详解以及注解详解。绝对是up亲身测验过的，绝对好用！！！百度了很多内容，踩了很多坑后的整理版。
SpringBoot快速教程三整合Knife4j
最新发布
CodingSir168的博客
09-26 1379
通过SpringBoot3.3.4版本整合目前主流的接口文档框架Knife4j的新版本，因为SpringBoot3只支持OpenAI3规范，所以本篇是通过整合Knife4j的4.4版本进行演示接口文档框架的应用。注意：jdk至少>=17哈，别问为什么，问了就告诉你！
SpringBoot 3 整合Swagger3.0或Knife4j
Java小白的博客
01-10 717
spring boot3.X之后整合swagger添加依赖为。Swagger2.0到Swagger3.0常用注解变更。整合增强版swagger。
Springboot 3.0.0 整合swagger
weixin_44353972的博客
12-14 2862
swagger3.0.0
最完整版-Springboot3集成Knife4j
学习记录
08-22 3788
在使用时我觉得它的样式和蓝色主色调不符合我的审美，所以我觉得使用一个更强的工具Knife4j。Knife4j是一个用于SpringBoot和SpringCloud的增强Swagger的工具，提供黑色主题和更多配置选项。Knife4j在更名之前，原来的名称是叫swagger-bootstrap-ui，这是两种不一样风格的ui显示，将原来的蓝色变成炫酷的黑色模式。二，Knife4j和swagger-bootstrap-ui对比工具状态风格配置Knife4j持久更新黑色主题支持配置文件编写配置项。
SpringBoot（三）整合Swagger3框架
你佳哥
12-28 1423
基于：【狂神说Java】SpringBoot最新教程IDEA版通俗易懂 目录1 前后端分离2 swagger简介3 使用3.1 导入依赖3.2 在启动主类注解@EnableOpenApi3.3 配置Swagger3Config3.4 访问使用4 总结 1 前后端分离 早些年，后端时代，前端写html、css静态页面交给后端，后端根据模板引擎改数据，跳转逻辑数据渲染，MVC模式； 前后端分离：后端控制层、服务层、数据访问层；前端控制层、视图层；交互靠API接口传JSON； 2 swagger简介 Res
spring boot3 集成swagger3
不要和代码过不去
07-20 4263
1 设置pom.xml 主要是引入nexus-maven，com.github.xiaoymin 2个，cn.hutool，org.springframework。2随意位置创建 SwaggerConfig。3修改 DemoApplication。4:给控制文件添加对应注解。
Springboot 3整合Knife4j（Swagger3、OpenApi3）
桃吱咬咬_的博客
07-08 3653
Springboot 3.x项目中使用Knife4j
springboot3.0.11-SNAPSHOT使用knife4j-openapi3所遇见的问题
m0_71683629的博客
09-15 2676
可以访问swagger -ui但是无法访问doc.html，关于在doc.html找不到图标的问题，knife4j-openapi3简单的运用
Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案
10-09
Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案。前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活。提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分。提供更多灵活的...
Knife4j各版本集成SpringBoot 2.x 3.x版本demo示例
04-23
同样，替换`{knife4j_version_for_springboot_3}`为适用的版本。 集成完成后，我们需要配置Swagger的元数据。在Spring Boot应用的配置类中，添加以下代码： ```java @Configuration @EnableSwagger2Doc public ...
【SpringBoot】22、SpringBoot中整合knife4j接口文档
热门推荐
Asurplus
07-02 21万+
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护 接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护 一、界面先赏 1、首页 2、接口文档 3、调试 二、整合 knife4j 1、引入 maven 依赖 <!-- knife4j接口文档 start --> <dependency> &lt
SpringBoot整合Swagger3.0
qq_51569224的博客
07-18 2641
SpringBoot整合Swagger3.0
Spring Boot3整合knife4j(swagger3)
蒾酒的博客
01-23 6601
Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)作者的使用的spring boot 3.2.2为当前最新版，所以依赖导入最新的knife4j 4.4.0。3.1 增强模式 | Knife4j (xiaominfo.com)好一个spring boot项目且版本为3X，项目可正常启动。快速开始 | Knife4j (xiaominfo.com)接下来配置以下接口文档的作者等信息。@Tag注解：标记接口类别。
Springboot3 集成knife4j(swagger)
清山博客
04-02 1289
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!2.Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突。版本集成knife4j叙述(请注意版本差别，不同版本写法不同)。1.Spring Boot 3 只支持OpenAPI3规范。3.JDK版本必须 >= 17。
springboot3集成Swagger3
小魏做编程
03-08 921
http://localhost:端口号/swagger-ui/index.html。http://localhost:端口号/swagger-ui/index.html。
【web】Springboot3 集成 Swagger3
m0_52733659的博客
01-06 675
对接口使用 @Operation。对控制器使用 @Tag。
Spring Boot 3项目集成Swagger3教程
interest_ing_的博客
03-07 1万+
Swagger是一个用于设计、构建、记录和使用RESTful web服务的开源软件框架。Swagger 3（OpenAPI 3.0）提供了更加强大和灵活的API文档生成能力。本教程将指导您如何在Spring Boot 3项目中集成Swagger3，并使用Knife4j作为UI界面。
knife4j-openapi2-spring-boot-starter与knife4j-openapi3-spring-boot-starter与knife4j-openapi3-jakarta-spring-boot-starter
05-12
knife4j-openapi2-spring-boot-starter、knife4j-openapi3-spring-boot-starter和knife4j-openapi3-jakarta-spring-boot-starter都是基于Spring Boot的开源API文档生成工具Knife4j的扩展库。 其中，knife4j-openapi2-spring-boot-starter适用于OpenAPI2规范（也称Swagger2），而knife4j-openapi3-spring-boot-starter和knife4j-openapi3-jakarta-spring-boot-starter则适用于OpenAPI3规范（也称Swagger3）。前者与后者的主要区别在于OpenAPI3规范引入了一些新的概念，如Components、Responses、RequestBody等，同时也新增了对YAML格式的支持。 这三个扩展库的主要功能是基于Java注解自动生成API文档，包括接口信息、参数、返回值、错误码等内容，并提供了一些UI界面以方便查看和测试API接口。同时，它们也支持一些高级功能，如多语言支持、权限控制、集成Spring Security等。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值