技术标签: spring spring boot 解决方案 java 后端 api
Swagger2(基于openApi3)已经在17年停止维护了,取而代之的是 sagger3(基于openApi3),而国内几乎没有 sagger3使用的文档,百度搜出来的都是swagger2的使用,这篇文章将介绍如何在 java 中使用 openApi3(swagger3)。
OpenApi是业界真正的 api 文档标准,其是由 Swagger 来维护的,并被linux列为api标准,从而成为行业标准。
swagger 是一个 api 文档维护组织,后来成为了 Open API 标准的主要定义者,现在最新的版本为17年发布的 Swagger3(Open Api3)。
国内绝大部分人还在用过时的swagger2(17年停止维护并更名为swagger3)
swagger2的包名为 io.swagger
,而swagger3的包名为 io.swagger.core.v3
。
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 5
,Webflux
(仅请求映射支持,尚不支持功能端点)、Spring Integration
pringfox-boot-starter
以后可以直接依赖一个 dependencySpringDoc也是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger3 集成到 Spring 中。
也是用来在 Spring 中帮助开发者生成文档,并可以轻松的在spring boot中使用。
该组织下的项目支持swagger页面Oauth2登录(Open API3的内容),相较 SpringFox来说,它的支撑时间更长,无疑是更好的选择。但由于国内发展较慢,在国内不容易看到太多有用的文档,不过可以访问它的官网。它的使用了 swagger3(OpenAPI3),但 swagger3 并未对 swagger2 的注解做兼容,不易迁移,也因此,名气并不如 spring fox。
pom.xml 里去掉 springfox 或者 swagger 的依赖。添加springdoc-openapi-ui
。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.3.1</version>
</dependency>
这一步是可选的,因为改动太大,故 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将注解名称规范化,工程化。
旧:
@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/**
参见这篇
https://springdoc.org/faq.html#how-can-i-deploy-the-doploy-springdoc-openapi-ui-behind-a-reverse-proxy.
https://springdoc.org/faq.html#how-can-i-configure-swagger-ui.
https://springdoc.org/faq.html#how-can-i-hide-an-operation-or-a-controller-from-documentation-.
文章浏览阅读429次。大牛博客: 阮一峰博客:http://www.ruanyifeng.com/blog/ 愚人码头博客:http://www.css88.com/ 张鑫旭博客:http://www.zhangxinxu.com/wordpress/ 勾三股四博客:http://jiongks.name/ 前端博客:http://caibaojian.com/ 大漠穷秋:https://my.oschin..._工具类网站
文章浏览阅读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安装提示已安装这个产品的另一个版本
文章浏览阅读417次。Java2平台包括:标准版(J2SE)、企业版(J2EE)和微缩版(J2ME)三个版本。J2SE,J2ME和J2EE,这也就是SunONE(Open NetEnvironment)体系。J2SE就是Java2的标准版,主要用于桌面应用软件的编程;J2ME主要应用于嵌入式系统开发,如手机和PDA的编程;J2EE是Java2的企业版,主要用于分布式的网络程序的开发,如电子商务网站和ERP系统。_j2ee和j2se和j2we
文章浏览阅读5k次,点赞6次,收藏46次。一、矩概念详解矩这个东西,能组成的名词太多了,矩形,就是长方形,矩阵,就是m行n列的二维数组,所以想了解矩,就要从其具体的场景中去理解。今天我们要讲的图像矩,就是一个新的概念,图像矩就是图像的矩,这个概念来源于数学中的矩,所以我们要先来理解一下,数学中的矩。首先我们先来看一下它的定义和相关概念: 在数学和统计..._信号的四阶矩和三阶矩
文章浏览阅读1.5k次。目录scratch旋转填充三角形一、题目要求1、准备工作2、功能实现二、案例分析1、角色分析2、背景分析3、前期准备三、实现流程1、案例分析2、详细过程四、程序编写五、考点分析六、推荐资料1、入门基础2、蓝桥杯比赛3、考级资料4、视频课程scratch旋转填充三角形一、题目要求背景为白色、正六边形和三角形填充颜色分别为红色、绿色 图形中间为边长为80的正六边形,周围为六个等边三角形 正六边形的上下两条边要求..._scratch教程100例
文章浏览阅读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
文章浏览阅读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
文章浏览阅读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
文章浏览阅读1.3k次,点赞3次,收藏12次。vue路由守卫钩子函数~完整的生命周期~keep-alive用法~_vue-router 生命周期
文章浏览阅读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
文章浏览阅读2.3w次,点赞49次,收藏502次。首先,介绍了LMS自适应滤波器的特点和应用;其次,对LMS滤波器的原理进行推导,得到算法最核心的表达式;最后,给出算法的MATLAB实现以及使用案例。_lms滤波
文章浏览阅读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 翻译