【SpringBoot3】集成Knife4j、springdoc-openapi作为接口文档

最新推荐文章于 2024-03-26 14:33:57 发布
最新推荐文章于 2024-03-26 14:33:57 发布
阅读量3.7k 收藏 35
点赞数 18
分类专栏： SpringBoot 3.0 从入门到精通 文章标签： springboot knife4j swagger springdoc
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/wlddhj/article/details/135914060
版权

一、什么是springdoc-openapi

Springdoc-openapi 是一个用于生成 OpenAPI（之前称为 Swagger）文档的库，专为 Spring Boot 应用程序设计。它可以根据你的 Spring MVC 控制器、REST 控制器和其他 Spring Bean 自动生成 OpenAPI 文档，从而帮助你在开发 RESTful API 时更加高效地管理和维护 API 文档。Springdoc-openapi 支持 OpenAPI 3.x 版本，并提供了一些额外的功能，如自定义配置、注解支持和与 Spring Boot 的无缝集成。

当你构建 RESTful API 时，API 文档是非常重要的，因为它们提供了对 API 的清晰描述，包括可用端点、请求参数、响应模型等信息。Springdoc-openapi 就是为了简化生成这些 API 文档而设计的。

Springdoc-openapi 的主要功能包括：

  1. 自动生成文档： Springdoc-openapi 可以自动扫描你的 Spring Boot 应用程序，并根据其中的控制器和其他相关组件生成 OpenAPI 文档。你无需手动编写文档，大部分信息都是自动生成的。

  2. 支持 OpenAPI 3.x： Springdoc-openapi 支持 OpenAPI 3.x 版本规范，这是当前 RESTful API 开发的主流规范。

  3. 注解支持： 它与 Spring MVC 注解和其他常见的 Spring 注解完全兼容，你可以使用这些注解来定制 API 的文档信息，例如请求参数的描述、响应的格式等。

  4. 自定义配置： Springdoc-openapi 提供了丰富的配置选项，你可以根据项目的需求进行自定义配置，以满足特定的文档生成需求。

  5. 集成简便： 由于 Springdoc-openapi 是专为 Spring Boot 应用程序设计的，因此它与 Spring Boot 无缝集成。你只需将 Springdoc-openapi 添加到项目的依赖中，它就会自动集成到你的应用程序中，开始生成 API 文档。

springdoc-openapi 使得生成和维护 RESTful API 文档变得简单而高效，帮助开发人员专注于业务逻辑而不是文档的编写。

在这里插入图片描述

核心注解

以下是 Springdoc-openapi 中一些常用的核心注解及其描述：

注解描述
@OpenAPIDefinition定义 OpenAPI 规范的基本信息，如 API 的标题、版本、服务器等
@Operation用于描述 API 操作（端点），包括操作的摘要、描述、请求和响应等信息
@ApiResponse定义操作的响应，包括响应的状态码、描述和响应模型等信息
@Parameter定义操作的参数，包括路径参数、查询参数、请求头参数等
@PathVariable定义路径参数，用于提取 URL 中的变量
@RequestParam定义查询参数，用于从请求中获取参数的值
@ApiParam在方法参数上使用，用于描述参数的含义和约束
@ApiResponses在控制器类上使用，为多个操作定义通用的响应规范
@ApiResponseExtension在 @Operation 或 @ApiResponse 上使用，用于扩展响应信息
@SecurityRequirement定义操作所需的安全要求，如需要的身份验证方案、安全范围等
@SecurityScheme定义安全方案，包括认证方式（如 Basic、OAuth2 等）、令牌 URL、授权 URL 等
@Tags定义操作的标签，用于对操作进行分类和组织
@Hidden在文档中隐藏标记的操作或参数，可以用于隐藏一些内部或不需要在文档中展示的部分
@Extension用于为生成的 OpenAPI 文档添加自定义的扩展信息，可以在文档中增加额外的元数据或自定义字段
@RequestBodySchema定义请求体的数据模型，允许对请求体进行更细粒度的描述和约束，如属性的名称、类型、格式、必填性等
@ApiResponseSchema定义响应的数据模型，允许对响应体进行更细粒度的描述和约束，如属性的名称、类型、格式、必填性等
@ExtensionProperty在 @Extension 注解上使用，用于定义自定义扩展的属性，可以添加额外的元数据或自定义字段到生成的 OpenAPI 文档中

这些注解可以帮助开发者更精细地描述 API 的各个方面，从而生成更加详细和准确的 OpenAPI 文档。

从 Swagger 2 升级为 Swagger 3

下面是将 Swagger 2 注解替换为 Swagger 3 注解的翻译：

  • @Api → @Tag
  • @ApiIgnore → @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @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”)

这些转换可以帮助将现有的 Swagger 2 注解替换为 Swagger 3 注解，以便与 Springdoc-openapi-starter-webmvc-ui 库一起使用。

二、什么是Knife4j

Knife4j 是一个基于 Swagger 实现的接口文档管理工具，它提供了一套简单易用的 UI 界面，用于展示和管理 Swagger 生成的 API 文档。与传统的 Swagger UI 相比，Knife4j 在 UI 设计和功能上进行了改进和增强，使得接口文档的浏览和管理更加方便和直观。

Knife4j 的特点和功能包括：

  1. 美观的界面设计： Knife4j 提供了一个美观、直观的界面，用户可以通过该界面轻松地浏览和理解 API 文档，以及进行相关操作。

  2. 增强的交互功能： Knife4j 在 Swagger UI 的基础上增加了一些交互功能，如请求参数的快速填充、响应结果的格式化显示等，提升了用户体验。

  3. 便捷的文档导航： Knife4j 提供了便捷的文档导航功能，用户可以通过目录结构快速定位到所需的接口文档，方便查阅和使用。

  4. 支持在线调试： Knife4j 允许用户在界面上直接进行接口调用和测试，无需额外的工具或插件，便可完成接口的调试和验证。

  5. 自动生成文档： Knife4j 可以直接集成到 Spring Boot 项目中，通过注解和配置自动生成接口文档，简化了文档编写的工作量。

总的来说，Knife4j 是一个功能强大、易用的接口文档管理工具，能够帮助开发者更加高效地管理和维护 API 文档，提升接口开发和调试的效率。

主要配置项

在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解

注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启

各个配置属性说明如下：

属性默认值说明值
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显示服务分组

三、SpringBoot3.0 集成 Knife4j 步骤

1、添加依赖（3.0和2.0不一样）

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
	<version>4.4.0</version>
</dependency>
  • Spring Boot 3 只支持OpenAPI3规范
  • Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
  • JDK版本必须 >= 17

2、在 application.yml 中添加配置

springdoc:
  swagger-ui:
    tags-sorter: alpha
  group-configs:
    - group: bis
      display-name: "业务接口文档"
      paths-to-match: '/**'
      packages-to-scan: org.shi9.module.bis
    - group: system
      display-name: "系统接口文档"
      paths-to-match: '/**'
      packages-to-scan: org.shi9.module.system
  default-flat-param-object: true
knife4j:
  # 开启增强配置
  enable: true
  # 开启生产环境屏蔽（如果是生产环境，需要把下面配置设置true）
#  production: true
  setting:
    language: zh_cn
    swagger-model-name: 实体类列表
  basic: # 开始授权认证
    enable: true
    username: admin
    password: 123456

在 group-configs 下面配置不同的模块的接口分组，也可以通过代码配置，建议在yml中配置。代码配置类似如下：

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("springshop-public")
            .pathsToMatch("/public/**")
            .build();
}
@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("springshop-admin")
            .pathsToMatch("/admin/**")
            .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
            .build();
}

3、增加配置类 SwaggerConfig.java

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.shi9.common.constant.CommonConstant;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        Contact contact = new Contact();
        contact.setEmail("wlddhj@163.com");
        contact.setName("huangjian");
        contact.setUrl("http://doc.xiaominfo.com");
        return new OpenAPI()
                // 增加swagger授权请求头配置
                .components(new Components().addSecuritySchemes(CommonConstant.X_ACCESS_TOKEN,
                        new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme(CommonConstant.X_ACCESS_TOKEN)))
                .info(new Info()
                        .title("Shi9 后台服务API接口文档")
                        .version("1.0")
                        .contact(contact)
                        .description("Knife4j集成springdoc-openapi示例")
                        .termsOfService("http://doc.xiaominfo.com")
                        .license(new License().name("Apache 2.0")
                                .url("http://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

4、启动项目

项目启动后，直接打开地址 http://localhost:8081/doc.html，可以看见类型如下页面

在这里插入图片描述

参考

  • https://doc.xiaominfo.com/docs/quick-start
  • https://springdoc.org/#getting-started
  • https://springdoc.org/
  • https://gitee.com/xiaoym/knife4j
顽石九变
关注
  • 18
    点赞
  • 踩
  • 35
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
专栏目录
springdoc-openapi：具有spring-boot的OpenAPI 3库
01-29
致谢 介绍 springdoc-openapi Java库有助于使用Spring Boot项目自动生成API文档。 springdoc-openapi的工作原理是在运行时检查应用程序以基于Spring配置，类结构和各种注释来推断API语义。 该库会自动以JSON / YAML和HTML格式的页面生成文档。 可以使用swagger-api注释对生成的文档进行补充。 该库支持： OpenAPI 3 Spring启动（v1和v2） JSR-303，专门用于@ NotNull，@ Min，@ Max和@Size。 Swagger-ui Oauth 2 以下视频介绍了库： 这是一个基于社区的项目，不是由Spring Framework Contributors（Pivotal）维护的 入门 用于springdoc-openapi与spring-boot和swagger-ui集成的库 自动将swagger-ui部署到Spring Boot 2.x应用程序 使用官方的 ，将以HTML格式提供文档。 然后，应该在可以找到Swagger UI页面，OpenAPI描述将在json格式的
113-springboot-demo-knife4j-v3.rar
03-07
什么是Swagger？Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用：将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；当接口更新之后，只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了，从而规避了接口文档老旧不能使用的问题；通过 Swagger 页面，我们可以直接进行接口调用，降低了项目开发阶段的调试成本。 什么是Knife4J? 和Swagger什么关系？本质是Swagger的增强解决方案，前身只是一个SwaggerUI（swagger-bootstrap-ui）Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案, 前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!Knife4j的前身是swagger-bo
Knife4j 基础（OpenAPI3+SpringBoot2.7）
宋冠巡的博客
09-13 1640
本文按照官方文档，在 SpringBoot2.7 项目中，集成 Knife4j 的 OpenAPI3 版本。
SpringBoot2.6.3 + knife4j-openapi3
最新发布
qq_33141369的博客
03-26 432
description("这是基于Knife4j OpenApi3的接口文档")enable: true # 是否启用 knife4j 增强,如果只是使用 knife4j 的 UI,则可以关闭。.description("SpringBoot基础框架").info(new Info().title("API接口文档")// 开发者联系方式。启动后访问：localhost:8080/doc.html。enabled: true # 是否启用接口文档。# Basic认证用户名。# Basic认证密码。
一文了解Spring boot + open api 3.0 + knife4j的集成实例，提供开发时常用的API配置
HO1_K的博客
09-20 8578
spring boot 集成 open api 3.0，其基于swagger 2开发，且由官方维护。 通过knife4j增强其功能，在方便前后端接口调用的同时，也能快速生成离线文档。
【超详细】springboot + springdoc-openapi + knife4j 集成案例
BASK2312的博客
03-25 7976
java库有助于使用 spring boot 项目自动生成 API 文档。springdoc-openapi通过在运行时检查应用程序以根据 spring 配置、类结构和各种注释推断 API 语义来工作。自动生成 JSON/YAML 和 HTML 格式 API 的文档。可以使用 swagger-api 注释通过注释来完成此文档。该库支持：OpenAPI3Swagger-uiOAuth 2GraalVM 原生镜像Knife4j是一个集Swagger2和OpenAPI3为一体的增强解决方案。
Swagger和knife4j生成接口文档显示不出来的问题
m0_48362854的博客
06-15 4238
改完这个问题后发现仍然显示不出来接口文档,对应界面一直读取不出来,最后经过检查发现,在webmvcconfig文件进行资源放行的时候copy出错。其中有一个坑,就是前端的端口是90,后端端口8080,生成接口文档一定是输入后端接口。经过检查发现是在配置文件cv的时候把mybatis的配置打乱了 ,所以绑定不到。一定要注意idea下边的提示!注意yml的空格问题,经过重新配置后就正常了。SpringBoot版本号太高导致的问题。在配置文件中添加配置。
SpringBoot 整合 knfe4j ，使用 OpenAPI3 规范
N_007的博客
06-14 8935
SpringBoot + Knife4j ，生成API 文档
spring_boot整合knife4j
qingkong6178的博客
04-23 2203
knife4j是一个增强版本的swagger的前端ui，用来描述接口说明，接口测试相关。 本例使用的是jdk版本20，idea版本2023，knife4j4.1.0
SpringBoot集成Knife4j接口管理工具
竹林幽深
03-10 1052
原创 CodeLeader发表于陕西收录于合集#SpringBoot19个1、导入依赖包2、配置Knife4j3、放行Knife4j的请求4、使用Knife4j注解5、实现效果平时开发项目都用的是Swagger2或者Swagger3，但是这两个UI看起来不是很舒服，今天看到了Knife4j，它对Swagger进行了增强，有很多个性化需求。官网地址：https://doc.xiaominfo.com/
SpringBoot 3.0整合OpenAPI使用教程
竹林幽深
11-09 2515
原创 Web开发札记发表于江苏收录于合集#SpringBoot6个温馨提示Spring Boot 3 只支持OpenAPI3规范Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突JDK版本必须 >= 17。
springboot-knife4j 实现API文档
09-05
API文档
113-springboot-demo-knife4j-v2.rar
03-07
本质是Swagger的增强解决方案，前身只是一个SwaggerUI（swagger-bootstrap-ui）Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案, 前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,...
Springboot2整合knife4j过程解析
08-24
主要介绍了Springboot2整合knife4j过程解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
Knife4j各版本集成SpringBoot 2.x 3.x版本demo示例
04-23
Knife4j各版本集成SpringBoot 2.x 3.x版本demo示例，亲测可用 ，仅供学习使用。
springBoo3.0集成knife4j4.1.0（swagger3）
qq_45001053的博客
03-31 5780
springBoot3.0集成swagger3的过程步骤
Springboot 2.7 集成 Swagger 增强版接口框架 Knife4j 4.3 + springdoc OpenApi 3.0
Mrqiang9001
08-15 6180
Swagger 作为一款服务端接口文档自动生成框架，早已深入人心，并且在市场上得到了广泛的应用。然而，Swagger 3.0 也就是 OpenApi 3.0 规范发布之后便停止了更新维护，出道就是巅峰。Knife4j 作为 Swagger 的增强版，是对 Swagger UI 做了优化，同时还有很多增强的功能。伴随着 Swagger 3.0 的停止更新，如今 Knife4j 从4.0开始已经逐渐使用 Springdoc 作为 swagger 的替代。
SpringBoot3整合swagger（springdoc-openapi）
热门推荐
蓝影铁哥的博客
06-01 1万+
SpringBoot3、swagger3、springdoc-openapi、jdk17
springdoc-openapi knife4j
10-13
springdoc-openapi和knife4j都是基于Swagger的开源框架，用于生成和展示RESTful API文档。其中，springdoc-openapi是一个Spring Boot的库，可以通过注解自动生成OpenAPI文档，而knife4j是一个基于springdoc-openapi的增强UI实现，提供了更加美观和易用的API文档展示界面。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

顽石九变

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

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

余额充值