0


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

一、什么是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.enable

false是否开启Knife4j增强模式

knife4j.cors

false是否开启一个默认的跨域配置,该功能配合自定义Host使用

knife4j.production

false是否开启生产环境保护策略

knife4j.basic

对Knife4j提供的资源提供BasicHttp校验,保护文档

knife4j.basic.enable

false关闭BasicHttp功能

knife4j.basic.username

basic用户名

knife4j.basic.password

basic密码

knife4j.documents

自定义文档集合,该属性是数组

knife4j.documents.group

所属分组

knife4j.documents.name

类似于接口中的tag,对于自定义文档的分组

knife4j.documents.locations

markdown文件路径,可以是一个文件夹(

classpath:markdowns/*

),也可以是单个文件(

classpath:md/sign.md

)

knife4j.setting

前端Ui的个性化配置属性

knife4j.setting.enable-after-script

true调试Tab是否显示AfterScript功能,默认开启

knife4j.setting.language

zh-CNUi默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)

knife4j.setting.enable-swagger-models

true是否显示界面中SwaggerModel功能

knife4j.setting.swagger-model-name
Swagger Models

重命名SwaggerModel名称,默认

knife4j.setting.enable-document-manage

true是否显示界面中"文档管理"功能

knife4j.setting.enable-reload-cache-parameter

false是否在每个Debug调试栏后显示刷新变量按钮,默认不显示

knife4j.setting.enable-version

false是否开启界面中对某接口的版本控制,如果开启,后端变化后Ui界面会存在小蓝点

knife4j.setting.enable-request-cache

true是否开启请求参数缓存

knife4j.setting.enable-filter-multipart-apis

false针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址

knife4j.setting.enable-filter-multipart-api-method-type

POST具体接口的过滤类型

knife4j.setting.enable-host

false是否启用Host

knife4j.setting.enable-host-text

falseHOST地址

knife4j.setting.enable-home-custom

false是否开启自定义主页内容

knife4j.setting.home-custom-path

主页内容Markdown文件路径

knife4j.setting.enable-search

false是否禁用Ui界面中的搜索框

knife4j.setting.enable-footer

true是否显示Footer

knife4j.setting.enable-footer-custom

false是否开启自定义Footer

knife4j.setting.footer-custom-content

false自定义Footer内容

knife4j.setting.enable-dynamic-parameter

false是否开启动态参数调试功能

knife4j.setting.enable-debug

true启用调试

knife4j.setting.enable-open-api

true显示OpenAPI规范

knife4j.setting.enable-group

true显示服务分组

三、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:trueknife4j:# 开启增强配置enable:true# 开启生产环境屏蔽(如果是生产环境,需要把下面配置设置true)#  production: truesetting:language: zh_cn
    swagger-model-name: 实体类列表
  basic:# 开始授权认证enable:trueusername: admin
    password:123456

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

@BeanpublicGroupedOpenApipublicApi(){returnGroupedOpenApi.builder().group("springshop-public").pathsToMatch("/public/**").build();}@BeanpublicGroupedOpenApiadminApi(){returnGroupedOpenApi.builder().group("springshop-admin").pathsToMatch("/admin/**").addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class)).build();}

3、增加配置类

SwaggerConfig.java
importio.swagger.v3.oas.models.Components;importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Contact;importio.swagger.v3.oas.models.info.Info;importio.swagger.v3.oas.models.info.License;importio.swagger.v3.oas.models.security.SecurityScheme;importorg.shi9.common.constant.CommonConstant;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;@ConfigurationpublicclassSwaggerConfig{@BeanpublicOpenAPIcustomOpenAPI(){Contact contact =newContact();
        contact.setEmail("[email protected]");
        contact.setName("huangjian");
        contact.setUrl("http://doc.xiaominfo.com");returnnewOpenAPI()// 增加swagger授权请求头配置.components(newComponents().addSecuritySchemes(CommonConstant.X_ACCESS_TOKEN,newSecurityScheme().type(SecurityScheme.Type.HTTP).scheme(CommonConstant.X_ACCESS_TOKEN))).info(newInfo().title("Shi9 后台服务API接口文档").version("1.0").contact(contact).description("Knife4j集成springdoc-openapi示例").termsOfService("http://doc.xiaominfo.com").license(newLicense().name("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0.html")));}}

4、启动项目

项目启动后,直接打开地址

http://localhost:8081/doc.html

,可以看见类型如下页面

在这里插入图片描述

参考


本文转载自: https://blog.csdn.net/wlddhj/article/details/135914060
版权归原作者 顽石九变 所有, 如有侵权,请联系我们删除。

“【SpringBoot3】集成Knife4j、springdoc-openapi作为接口文档”的评论:

还没有评论