Swagger3 注解使用(Open API 3)_swagger3注解-程序员宅基地

技术标签: spring  spring boot  解决方案  java  后端  api  

swagger 3 的使用

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

相关介绍

Open API

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

Swagger

swagger 是一个 api 文档维护组织,后来成为了 Open API 标准的主要定义者,现在最新的版本为17年发布的 Swagger3(Open Api3)。
国内绝大部分人还在用过时的swagger2(17年停止维护并更名为swagger3)
swagger2的包名为 io.swagger,而swagger3的包名为 io.swagger.core.v3

SpringFox

SpringFox是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger2 集成到 Spring 中。
常常用于 Spring 中帮助开发者生成文档,并可以轻松的在spring boot中使用。
截至2020年4月,都未支持 OpenAPI3 标准。

补充:2020.7.14 发布了 3.0 支持 OpenAPI3,github 发布记录 但官网对 3.0 版本相关文档未完善,还是只有 swagger 2.0 相关的。
升级到 OpenAPI3(java 中 swagger1.x 对应 OpenAPI2、swagger 2.x对应OpenAPI3)官方文档

3.0 相关特性

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

对应关系为:

swagger2 OpenAPI 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属性上

Swagger2 的注解命名以易用性切入,全是 Api 开头,在培养出使用者依赖注解的习惯后,Swagger 3将注解名称规范化,工程化。

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

旧:

   @Bean
    public 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());
    }
  
    @Bean
    public 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());
    }

新:

   @Bean
    public GroupedOpenApi publicApi() {
    
        return GroupedOpenApi.builder()
                .setGroup("springshop-public")
                .pathsToMatch("/public/**")
                .build();
    }
  
    @Bean
    public 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-.

版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/qq_35425070/article/details/105347336

智能推荐

前端开发必备网站_工具类网站-程序员宅基地

文章浏览阅读429次。大牛博客: 阮一峰博客:http://www.ruanyifeng.com/blog/ 愚人码头博客:http://www.css88.com/ 张鑫旭博客:http://www.zhangxinxu.com/wordpress/ 勾三股四博客:http://jiongks.name/ 前端博客:http://caibaojian.com/ 大漠穷秋:https://my.oschin..._工具类网站

Microsoft visual c++ 2015 redistributable 已安装这个产品的另一版本报错_visual studio安装提示已安装这个产品的另一个版本-程序员宅基地

文章浏览阅读8.7k次,点赞2次,收藏20次。安装Microsoft visual studio 2015时报错解决方法:控制面板–》添加或删除程序–》找到所有版本Microsoft visual c++ redistributable ,都删除–》重新安装Microsoft visual studio 2015tips:怕删不干净Microsoft visual studio 的一些组件,可以参照https://blog.csdn.net/qq_42158349/article/details/90901979文中,用totaluninst_visual studio安装提示已安装这个产品的另一个版本

J2SE、J2EE、J2ME的比较_j2ee和j2se和j2we-程序员宅基地

文章浏览阅读417次。Java2平台包括:标准版(J2SE)、企业版(J2EE)和微缩版(J2ME)三个版本。J2SE,J2ME和J2EE,这也就是SunONE(Open NetEnvironment)体系。J2SE就是Java2的标准版,主要用于桌面应用软件的编程;J2ME主要应用于嵌入式系统开发,如手机和PDA的编程;J2EE是Java2的企业版,主要用于分布式的网络程序的开发,如电子商务网站和ERP系统。_j2ee和j2se和j2we

矩概念与图像矩详解及其hu矩的运用_信号的四阶矩和三阶矩-程序员宅基地

文章浏览阅读5k次,点赞6次,收藏46次。一、矩概念详解矩这个东西,能组成的名词太多了,矩形,就是长方形,矩阵,就是m行n列的二维数组,所以想了解矩,就要从其具体的场景中去理解。今天我们要讲的图像矩,就是一个新的概念,图像矩就是图像的矩,这个概念来源于数学中的矩,所以我们要先来理解一下,数学中的矩。首先我们先来看一下它的定义和相关概念: 在数学和统计..._信号的四阶矩和三阶矩

【Scratch画图100例】图43-scratch旋转填充三角形 少儿编程 scratch编程画图案例教程 考级比赛画图集训案例_scratch教程100例-程序员宅基地

文章浏览阅读1.5k次。目录scratch旋转填充三角形一、题目要求1、准备工作2、功能实现二、案例分析1、角色分析2、背景分析3、前期准备三、实现流程1、案例分析2、详细过程四、程序编写五、考点分析六、推荐资料1、入门基础2、蓝桥杯比赛3、考级资料4、视频课程scratch旋转填充三角形一、题目要求背景为白色、正六边形和三角形填充颜色分别为红色、绿色 图形中间为边长为80的正六边形,周围为六个等边三角形 正六边形的上下两条边要求..._scratch教程100例

定义一个Cat类,拥有静态数据成员 numOfCats,记录Cat的个体数目;静态成员函数getNumOfCats(),读取numOfCats。设计程序测试这个类,体会静态数据成员和静态成员函数的用法_定义一个cat类,拥有静态数据成员howmanycats,记录cat的个体数目;静态成员函数geth-程序员宅基地

文章浏览阅读7.3k次,点赞10次,收藏55次。#include<iostream>using namespace std;class cat{ public: cat() { numOfCats++; } static int getNumOfCats() { return numOfCats; } ~cat() { numO._定义一个cat类,拥有静态数据成员howmanycats,记录cat的个体数目;静态成员函数geth

随便推点

网络安全漏洞分析小结_motw漏洞复现dump.bin-程序员宅基地

文章浏览阅读6k次,点赞4次,收藏21次。(一) 前言这里感谢师傅前面整理的通达OA一些版本的漏洞复现,这里从漏洞点出发,分析漏洞,从中学些一些师傅白盒挖掘漏洞的思路。​安装包下载地址,可以通过枚举版本号下载对应的安装包:https://cdndown.tongda2000.com/oa/2019/TDOA11.4.exehttps://www.tongda2000.com/download/down.php?VERSION=2019&code=安装教程为傻瓜式一键安装,这里不细说。默认账号密码admin/(空)【一&_motw漏洞复现dump.bin

Objective-C 中的 assign, copy,retain,strong,weak 详解-程序员宅基地

文章浏览阅读266次。Objective-C 中的 assign, copy,retain,strong,weak 详解 在IOS开发中,经常会使用 @property(nonatomic,copy)NSString * name; 语句来快速设置set get 方法,在此依次说明atomic 、nonatomic、copy 、retain的作用 at..._objective-c retain strong

vue生命周期、路由守卫、keep-alive_vue-router 生命周期-程序员宅基地

文章浏览阅读1.3k次,点赞3次,收藏12次。vue路由守卫钩子函数~完整的生命周期~keep-alive用法~_vue-router 生命周期

PRIVACY POLICY_privacy policyeffective date: 6th oct, 2021thank y-程序员宅基地

文章浏览阅读297次。Effective Date: 25th May 2018Thank you for playing our games! This Privacy Policy describes:§ The ways we collect personal data about you and why we do so§ How we use your personal data, and§ The choices you have about your personal data.This Priva_privacy policyeffective date: 6th oct, 2021thank you for playing our gam

【滤波器】最小均方(LMS)自适应滤波器_lms滤波-程序员宅基地

文章浏览阅读2.3w次,点赞49次,收藏502次。首先,介绍了LMS自适应滤波器的特点和应用;其次,对LMS滤波器的原理进行推导,得到算法最核心的表达式;最后,给出算法的MATLAB实现以及使用案例。_lms滤波

git提交警告Warning: Permanently added the RSA host key for IP address '13.250.177.223' to the list of_permanently added the ecdsa host key for ip addres-程序员宅基地

文章浏览阅读1.2w次,点赞2次,收藏3次。遇到的问题:git push时返回警告,如下图:虽然不处理一样可以提交代码,没有任何影响,但还是看着很不舒服。倘如想修改就按下面的方式处理。相关知识介绍:hosts文件的位置:1、Mac:/etc/hosts2、Windows: 在Windows 98系统下该文件在Windows目录,在Windows 2000/XP系统中位于X:\Winnt\System32\Drivers\Etc(或X:\Wi..._permanently added the ecdsa host key for ip address 翻译

推荐文章

热门文章

相关标签