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

相关文章

使用Docker构建Python Flask程序的详细教程

《使用Docker构建PythonFlask程序的详细教程》在当今的软件开发领域,容器化技术正变得越来越流行,而Docker无疑是其中的佼佼者,本文我们就来聊聊如何使用Docker构建一个简单的Py... 目录引言一、准备工作二、创建 Flask 应用程序三、创建 dockerfile四、构建 Docker

Python使用vllm处理多模态数据的预处理技巧

《Python使用vllm处理多模态数据的预处理技巧》本文深入探讨了在Python环境下使用vLLM处理多模态数据的预处理技巧,我们将从基础概念出发,详细讲解文本、图像、音频等多模态数据的预处理方法,... 目录1. 背景介绍1.1 目的和范围1.2 预期读者1.3 文档结构概述1.4 术语表1.4.1 核

Python使用pip工具实现包自动更新的多种方法

《Python使用pip工具实现包自动更新的多种方法》本文深入探讨了使用Python的pip工具实现包自动更新的各种方法和技术,我们将从基础概念开始,逐步介绍手动更新方法、自动化脚本编写、结合CI/C... 目录1. 背景介绍1.1 目的和范围1.2 预期读者1.3 文档结构概述1.4 术语表1.4.1 核

Conda与Python venv虚拟环境的区别与使用方法详解

《Conda与Pythonvenv虚拟环境的区别与使用方法详解》随着Python社区的成长,虚拟环境的概念和技术也在不断发展,:本文主要介绍Conda与Pythonvenv虚拟环境的区别与使用... 目录前言一、Conda 与 python venv 的核心区别1. Conda 的特点2. Python v

Spring Boot中WebSocket常用使用方法详解

《SpringBoot中WebSocket常用使用方法详解》本文从WebSocket的基础概念出发,详细介绍了SpringBoot集成WebSocket的步骤,并重点讲解了常用的使用方法,包括简单消... 目录一、WebSocket基础概念1.1 什么是WebSocket1.2 WebSocket与HTTP

C#中Guid类使用小结

《C#中Guid类使用小结》本文主要介绍了C#中Guid类用于生成和操作128位的唯一标识符,用于数据库主键及分布式系统,支持通过NewGuid、Parse等方法生成,感兴趣的可以了解一下... 目录前言一、什么是 Guid二、生成 Guid1. 使用 Guid.NewGuid() 方法2. 从字符串创建

Knife4j+Axios+Redis前后端分离架构下的 API 管理与会话方案(最新推荐)

《Knife4j+Axios+Redis前后端分离架构下的API管理与会话方案(最新推荐)》本文主要介绍了Swagger与Knife4j的配置要点、前后端对接方法以及分布式Session实现原理,... 目录一、Swagger 与 Knife4j 的深度理解及配置要点Knife4j 配置关键要点1.Spri

Python使用python-can实现合并BLF文件

《Python使用python-can实现合并BLF文件》python-can库是Python生态中专注于CAN总线通信与数据处理的强大工具,本文将使用python-can为BLF文件合并提供高效灵活... 目录一、python-can 库:CAN 数据处理的利器二、BLF 文件合并核心代码解析1. 基础合

Python使用OpenCV实现获取视频时长的小工具

《Python使用OpenCV实现获取视频时长的小工具》在处理视频数据时,获取视频的时长是一项常见且基础的需求,本文将详细介绍如何使用Python和OpenCV获取视频时长,并对每一行代码进行深入解析... 目录一、代码实现二、代码解析1. 导入 OpenCV 库2. 定义获取视频时长的函数3. 打开视频文

Spring IoC 容器的使用详解(最新整理)

《SpringIoC容器的使用详解(最新整理)》文章介绍了Spring框架中的应用分层思想与IoC容器原理,通过分层解耦业务逻辑、数据访问等模块,IoC容器利用@Component注解管理Bean... 目录1. 应用分层2. IoC 的介绍3. IoC 容器的使用3.1. bean 的存储3.2. 方法注