江苏网站建设,淄博公司做网站,快速网站推广优化,律师个人网站有用吗一、什么是springdoc-openapi
Springdoc-openapi 是一个用于生成 OpenAPI#xff08;之前称为 Swagger#xff09;文档的库#xff0c;专为 Spring Boot 应用程序设计。它可以根据你的 Spring MVC 控制器、REST 控制器和其他 Spring Bean 自动生成 OpenAPI 文档#xff0c…一、什么是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 的主要功能包括 自动生成文档 Springdoc-openapi 可以自动扫描你的 Spring Boot 应用程序并根据其中的控制器和其他相关组件生成 OpenAPI 文档。你无需手动编写文档大部分信息都是自动生成的。 支持 OpenAPI 3.x Springdoc-openapi 支持 OpenAPI 3.x 版本规范这是当前 RESTful API 开发的主流规范。 注解支持 它与 Spring MVC 注解和其他常见的 Spring 注解完全兼容你可以使用这些注解来定制 API 的文档信息例如请求参数的描述、响应的格式等。 自定义配置 Springdoc-openapi 提供了丰富的配置选项你可以根据项目的需求进行自定义配置以满足特定的文档生成需求。 集成简便 由于 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 → TagApiIgnore → Parameter(hidden true) 或 Operation(hidden true) 或 HiddenApiImplicitParam → ParameterApiImplicitParams → ParametersApiModel → SchemaApiModelProperty(hidden true) → Schema(accessMode READ_ONLY)ApiModelProperty → SchemaApiOperation(value “foo”, notes “bar”) → Operation(summary “foo”, description “bar”)ApiParam → ParameterApiResponse(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 的特点和功能包括 美观的界面设计 Knife4j 提供了一个美观、直观的界面用户可以通过该界面轻松地浏览和理解 API 文档以及进行相关操作。 增强的交互功能 Knife4j 在 Swagger UI 的基础上增加了一些交互功能如请求参数的快速填充、响应结果的格式化显示等提升了用户体验。 便捷的文档导航 Knife4j 提供了便捷的文档导航功能用户可以通过目录结构快速定位到所需的接口文档方便查阅和使用。 支持在线调试 Knife4j 允许用户在界面上直接进行接口调用和测试无需额外的工具或插件便可完成接口的调试和验证。 自动生成文档 Knife4j 可以直接集成到 Spring Boot 项目中通过注解和配置自动生成接口文档简化了文档编写的工作量。
总的来说Knife4j 是一个功能强大、易用的接口文档管理工具能够帮助开发者更加高效地管理和维护 API 文档提升接口开发和调试的效率。
主要配置项
在以前的版本中,开发者需要在配置文件中手动使用EnableKnife4j来使用增强自2.0.6版本后,只需要在配置文件中配置knife4j.enabletrue即可不在使用注解
注意要使用Knife4j提供的增强knife4j.enabletrue必须开启
各个配置属性说明如下
属性默认值说明值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是否启用Hostknife4j.setting.enable-host-textfalseHOST地址knife4j.setting.enable-home-customfalse是否开启自定义主页内容knife4j.setting.home-custom-path主页内容Markdown文件路径knife4j.setting.enable-searchfalse是否禁用Ui界面中的搜索框knife4j.setting.enable-footertrue是否显示Footerknife4j.setting.enable-footer-customfalse是否开启自定义Footerknife4j.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不一样
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactIdversion4.4.0/version
/dependencySpring Boot 3 只支持OpenAPI3规范Knife4j提供的starter已经引用springdoc-openapi的jar开发者需注意避免jar包冲突JDK版本必须 17 2、在 application.yml 中添加配置
springdoc:swagger-ui:tags-sorter: alphagroup-configs:- group: bisdisplay-name: 业务接口文档paths-to-match: /**packages-to-scan: org.shi9.module.bis- group: systemdisplay-name: 系统接口文档paths-to-match: /**packages-to-scan: org.shi9.module.systemdefault-flat-param-object: true
knife4j:# 开启增强配置enable: true# 开启生产环境屏蔽如果是生产环境需要把下面配置设置true
# production: truesetting:language: zh_cnswagger-model-name: 实体类列表basic: # 开始授权认证enable: trueusername: adminpassword: 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 {Beanpublic OpenAPI customOpenAPI() {Contact contact new Contact();contact.setEmail(wlddhj163.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-starthttps://springdoc.org/#getting-startedhttps://springdoc.org/https://gitee.com/xiaoym/knife4j
