Swagger3 注解使用（Open API 3）

您所在的位置：网站首页 › Service注解中的parameters属性的作用 › Swagger3 注解使用（Open API 3）

Swagger3 注解使用（Open API 3）

2023-11-04 10:55| 来源: 网络整理| 查看: 265

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。

org.springdoc springdoc-openapi-ui 1.3.1 使用 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@ParametersController 方法上@ApiImplicitParam@Parameter(description=“参数描述”)Controller 方法上 @Parameters 里@ApiParam@Parameter(description=“参数描述”)Controller 方法的参数上@ApiIgnore@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden-@ApiModel@SchemaDTO类上@ApiModelProperty@SchemaDTO属性上

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-.

【本文地址】

Swagger3 注解使用（Open API 3）

Swagger3 注解使用（Open API 3）

今日新闻

推荐新闻