OpenApi3/Swagger3簡單使用及與swagger2對比

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/**