Swagger3 注解使用（Open API 3.0）

---

前言

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

一、swagger 3 的使用

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中使用。目前已经支持 OpenAPI3 标准。

升级到 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 的注解命名以易用性切入，全是 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/**