Swagger3 註解使用（Open API 3）

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 標準。

SpringDoc

SpringDoc也是 spring 社區維護的一個項目（非官方），幫助使用者將 swagger3 集成到 Spring 中。
也是用來在 Spring 中幫助開發者生成文檔，並可以輕鬆的在spring boot中使用。

該組織下的項目支持swagger頁面Oauth2登錄（Open API3的內容），相較 SpringFox來說，它的支撐時間更長，無疑是更好的選擇。但由於國內發展較慢，在國內不容易看到太多有用的文檔，不過可以訪問它的官網。它的使用了 swagger3（OpenAPI3），但 swagger3 並未對 swagger2 的註解做兼容，不易遷移，也因此，名氣並不如 spring fox。

---

從 springfox 遷移

依賴變更

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 的

用 swagger 3 的註解（已經在上面引入）代替 swagger 2 的
(注意修改 swagger 3 註解的包路徑爲io.swagger.v3.oas.annotations.)

對應關係爲：

@ApiParam -> @Parameter
@ApiOperation -> @Operation
@Api -> @Tag
@ApiImplicitParams -> @Parameters
@ApiImplicitParam -> @Parameter
@ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiModel -> @Schema
@ApiModelProperty -> @Schema

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