Swagger 3 的使用
Swagger2已经在17年停止维护了,取而代之的是 Swagger3(基于openApi3),这篇文章将介绍如何在 java 中使用 OpenApi3(swagger3)以及与swagger2的对比。
1.基本介绍
1.1 Open API
OpenApi是业界真正的 api 文档标准,其是由 Swagger 来维护的,并被linux列为api标准,从而成为行业标准。
1.2 Swagger
swagger 是一个 api 文档维护组织,后来成为了 Open API 标准的主要定义者,现在最新的版本为17年发布的 Swagger3(Open Api3)。国内绝大部分人还在用过时的swagger2(17年停止维护并更名为swagger3)。swagger2的包名为 io.swagger,而swagger3的包名为 io.swagger.core.v3。
1.3 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)官方文档
1.4 swagger3 相关特性
- 支持 Spring 5,Webflux(仅请求映射支持,尚不支持功能端点)、Spring Integration
- 官方在 spring boot 的自动装配 pringfox-boot-starter 以后可以直接依赖一个 dependency
- 与swagger2.0更好的规范兼容性
- 支持OpenApi 3.0.3
- 轻依赖 spring-plugin,swagger-core
1.5 SpringDoc
SpringDoc也是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger3 集成到 Spring 中。
也是用来在 Spring 中帮助开发者生成文档,并可以轻松的在spring boot中使用。
该组织下的项目支持swagger页面Oauth2登录(Open API3的内容),相较 SpringFox来说,它的支撑时间更长,无疑是更好的选择。但由于国内发展较慢,在国内不容易看到太多有用的文档,不过可以访问它的官网。它的使用了 swagger3(OpenAPI3),但 swagger3 并未对 swagger2 的注解做兼容,不易迁移,也因此,名气并不如 spring fox。
2.开始使用
2.1 从 spring-fox 迁移到 springdoc
依赖变更
pom.xml 里去掉 springfox 或者 swagger 的依赖,添加springdoc-openapi-ui。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.2</version>
</dependency>
2.2 Swagger3与 Swagger2注解对比使用
使用 swagger3 注解代替 swagger2 的(为可选项)
Swagger3 | Swagger2 | 注解说明 |
@Tag(name = “接口类描述”) | @Api | Controller 类 |
@Operation(summary =“接口方法描述”) | @ApiOperation | Controller 方法 |
@Parameters | @ApiImplicitParams | Controller 方法 |
@Parameter(description=“参数描述”) | @ApiImplicitParam @ApiParam | Controller 方法上 @Parameters 里 Controller 方法的参数 |
@Parameter(hidden = true) @Operation(hidden = true) @Hidden | @ApiIgnore | 排除或隐藏api |
@Schema | @ApiModel @ApiModelProperty | DTO实体 DTO实体属性 |
Swagger2 的注解命名以易用性切入,全是 Api 开头,在培养出使用者依赖注解的习惯后,Swagger 3将注解名称规范化,工程化。
2.3 Api 分组配置
Swagger2 配置:
@Bean
public Docket publicApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
.paths(PathSelectors.regex("/api/v1/public.*"))
.build()
.groupName("spring-app-public")
.apiInfo(apiInfo());
}
Swagger3配置:
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.setGroup("spring-app-public")
.pathsToMatch("/api/v1/public/**")
.build();
}
Swagger3用配置文件替代代码配置:
springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/api/v1/public/**