大家好,又见面了,我是你们的朋友全栈君。如果您正在找激活码,请点击查看最新教程,关注关注公众号 “全栈程序员社区” 获取激活教程,可能之前旧版本教程已经失效.最新Idea2022.1教程亲测有效,一键激活。
Jetbrains全家桶1年46,售后保障稳定
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 5
,Webflux
(仅请求映射支持,尚不支持功能端点)、Spring Integration
- 补充官方在 spring boot 的自动装配
pringfox-boot-starter
以后可以直接依赖一个 dependency - 与2.0更好的规范兼容性
- 支持OpenApi 3.0.3
- 轻依赖 spring-plugin,swagger-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-.
发布者:全栈程序员-用户IM,转载请注明出处:https://javaforall.cn/213538.html原文链接:https://javaforall.cn
【正版授权,激活自己账号】: Jetbrains全家桶Ide使用,1年售后保障,每天仅需1毛
【官方授权 正版激活】: 官方授权 正版激活 支持Jetbrains家族下所有IDE 使用个人JB账号...