Swagger3 注解使用(Open API 3)

2024-04-29 17:04
文章标签 使用 注解 api open swagger3

本文主要是介绍Swagger3 注解使用(Open API 3),希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

一、swagger 3 的使用

Swagger2(基于openApi3)已经在17年停止维护了,取而代之的是 sagger3(基于openApi3),而国内几乎没有 sagger3使用的文档,百度搜出来的都是swagger2的使用,这篇文章将介绍如何在 java 中使用 openApi3(swagger3)。

相关介绍:

1. Open API

OpenApi是业界真正的 api 文档标准,其是由 Swagger 来维护的,并被linux列为api标准,从而成为行业标准。

2. Swagger

swagger 是一个 api 文档维护组织,后来成为了 Open API 标准的主要定义者,现在最新的版本为17年发布的 Swagger3(Open Api3)。

国内绝大部分人还在用过时的swagger2(17年停止维护并更名为swagger3)

swagger2的包名为 io.swagger,而swagger3的包名为 io.swagger.core.v3。

3. SpringFox

SpringFox是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger2 集成到 Spring 中。

常常用于 Spring 中帮助开发者生成文档,并可以轻松的在spring boot中使用。

升级到 OpenAPI3 官方文档

(java 中 swagger1.x 对应 OpenAPI2、swagger 2.x对应OpenAPI3)

3.0 相关特性

  • 支持 Spring 5,Webflux(仅请求映射支持,尚不支持功能端点)、Spring Integration
  • 补充官方在 spring boot 的自动装配 pringfox-boot-starter 以后可以直接依赖一个 dependency
  • 与2.0更好的规范兼容性
  • 支持OpenApi 3.0.3
  • 轻依赖 spring-plugin,swagger-core
  • 现有的swagger2批注将继续有效并丰富开放式API 3.0规范

4. SpringDoc

SpringDoc也是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger3 集成到 Spring 中。

也是用来在 Spring 中帮助开发者生成文档,并可以轻松的在spring boot中使用。

该组织下的项目支持swagger页面Oauth2登录(Open API3的内容),相较 SpringFox来说,它的支撑时间更长,无疑是更好的选择。但由于国内发展较慢,在国内不容易看到太多有用的文档,不过可以访问它的官网。它使用了 swagger3(OpenAPI3),但 swagger3 并未对 swagger2 的注解做兼容,不易迁移,也因此,名气并不如 spring fox。

二、从 spring-fox 迁移到 springdoc

依赖变更
pom.xml 里去掉 springfox 或者 swagger 的依赖。添加springdoc-openapi-ui。

   <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.3.1</version></dependency>

使用 swagger3 注解代替 swagger2 的(可选)

这一步是可选的,因为改动太大,故 springfox对旧版的 swagger做了兼容处理。

但不知道未来会不会不兼容,这里列出如何用 swagger 3 的注解(已经在上面引入)代替 swagger 2 的 (注意修改 swagger 3 注解的包路径为io.swagger.v3.oas.annotations.)

对应关系为:

swagger2OpenAPI 3注解位置
@Api @Tag(name = “接口类描述”) Controller 类上
@ApiOperation@Operation(summary =“接口方法描述”) Controller 方法上
@ApiImplicitParams @Parameters Controller 方法上
@ApiImplicitParam@Parameter(description=“参数描述”) 

Controller 方法上

@Parameters 里

@ApiParam@Parameter(description=“参数描述”) Controller 方法的参数上
@ApiIgnore  

@Parameter(hidden = true)

或 @Operation(hidden = true)

或 @Hidden

-
@ApiModel@Schema  DTO类上
@ApiModelProperty @Schema  DTO属性上

修改Api 分组(当且仅当你之前定义了多个 Docket Bean)
旧:

   @Beanpublic Docket publicApi() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public")).paths(PathSelectors.regex("/public.*")).build().groupName("springshop-public").apiInfo(apiInfo());}@Beanpublic Docket adminApi() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin")).paths(PathSelectors.regex("/admin.*")).build().groupName("springshop-admin").apiInfo(apiInfo());}

   @Beanpublic GroupedOpenApi publicApi() {return GroupedOpenApi.builder().setGroup("springshop-public").pathsToMatch("/public/**").build();}@Beanpublic GroupedOpenApi adminApi() {return GroupedOpenApi.builder().setGroup("springshop-admin").pathsToMatch("/admin/**").build();}

如果之前只有一个 Docket,则把他删了,用配置文件替代它

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

其他情况

swagger ui在代理的后面,如 nginx
参见这篇
https://springdoc.org/faq.html#how-can-i-deploy-the-doploy-springdoc-openapi-ui-behind-a-reverse-proxy.

自定义 Swagger UI
https://springdoc.org/faq.html#how-can-i-configure-swagger-ui.

在文档中隐藏某个接口或者 Controller
https://springdoc.org/faq.html#how-can-i-hide-an-operation-or-a-controller-from-documentation-.

这篇关于Swagger3 注解使用(Open API 3)的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/946648

相关文章

postgresql使用UUID函数的方法

《postgresql使用UUID函数的方法》本文给大家介绍postgresql使用UUID函数的方法,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友参考下吧... 目录PostgreSQL有两种生成uuid的方法。可以先通过sql查看是否已安装扩展函数,和可以安装的扩展函数

spring中的@MapperScan注解属性解析

《spring中的@MapperScan注解属性解析》@MapperScan是Spring集成MyBatis时自动扫描Mapper接口的注解,简化配置并支持多数据源,通过属性控制扫描路径和过滤条件,利... 目录一、核心功能与作用二、注解属性解析三、底层实现原理四、使用场景与最佳实践五、注意事项与常见问题六

如何使用Lombok进行spring 注入

《如何使用Lombok进行spring注入》本文介绍如何用Lombok简化Spring注入,推荐优先使用setter注入,通过注解自动生成getter/setter及构造器,减少冗余代码,提升开发效... Lombok为了开发环境简化代码,好处不用多说。spring 注入方式为2种,构造器注入和setter

MySQL中比较运算符的具体使用

《MySQL中比较运算符的具体使用》本文介绍了SQL中常用的符号类型和非符号类型运算符,符号类型运算符包括等于(=)、安全等于(=)、不等于(/!=)、大小比较(,=,,=)等,感兴趣的可以了解一下... 目录符号类型运算符1. 等于运算符=2. 安全等于运算符<=>3. 不等于运算符<>或!=4. 小于运

使用zip4j实现Java中的ZIP文件加密压缩的操作方法

《使用zip4j实现Java中的ZIP文件加密压缩的操作方法》本文介绍如何通过Maven集成zip4j1.3.2库创建带密码保护的ZIP文件,涵盖依赖配置、代码示例及加密原理,确保数据安全性,感兴趣的... 目录1. zip4j库介绍和版本1.1 zip4j库概述1.2 zip4j的版本演变1.3 zip4

Python 字典 (Dictionary)使用详解

《Python字典(Dictionary)使用详解》字典是python中最重要,最常用的数据结构之一,它提供了高效的键值对存储和查找能力,:本文主要介绍Python字典(Dictionary)... 目录字典1.基本特性2.创建字典3.访问元素4.修改字典5.删除元素6.字典遍历7.字典的高级特性默认字典

使用Python构建一个高效的日志处理系统

《使用Python构建一个高效的日志处理系统》这篇文章主要为大家详细讲解了如何使用Python开发一个专业的日志分析工具,能够自动化处理、分析和可视化各类日志文件,大幅提升运维效率,需要的可以了解下... 目录环境准备工具功能概述完整代码实现代码深度解析1. 类设计与初始化2. 日志解析核心逻辑3. 文件处

一文详解如何使用Java获取PDF页面信息

《一文详解如何使用Java获取PDF页面信息》了解PDF页面属性是我们在处理文档、内容提取、打印设置或页面重组等任务时不可或缺的一环,下面我们就来看看如何使用Java语言获取这些信息吧... 目录引言一、安装和引入PDF处理库引入依赖二、获取 PDF 页数三、获取页面尺寸(宽高)四、获取页面旋转角度五、判断

C++中assign函数的使用

《C++中assign函数的使用》在C++标准模板库中,std::list等容器都提供了assign成员函数,它比操作符更灵活,支持多种初始化方式,下面就来介绍一下assign的用法,具有一定的参考价... 目录​1.assign的基本功能​​语法​2. 具体用法示例​​​(1) 填充n个相同值​​(2)

Spring StateMachine实现状态机使用示例详解

《SpringStateMachine实现状态机使用示例详解》本文介绍SpringStateMachine实现状态机的步骤,包括依赖导入、枚举定义、状态转移规则配置、上下文管理及服务调用示例,重点解... 目录什么是状态机使用示例什么是状态机状态机是计算机科学中的​​核心建模工具​​,用于描述对象在其生命