Swagger3.0新版帶來的新變化

導讀	在社群的推動下，Springfox3.0 去年 7 月份就釋出了，最近終於得空和小夥伴們聊一聊新版本的新變化。這次的版本升級估計小夥伴們都翹首以待好久了，畢竟上一次發版已經是兩年前的事情了。

在社群的推動下，Springfox3.0 去年 7 月份就釋出了，最近終於得空和小夥伴們聊一聊新版本的新變化。這次的版本升級估計小夥伴們都翹首以待好久了，畢竟上一次發版已經是兩年前的事情了。

新版本還是有很多好玩的地方，我們一起來看下。

OpenAPI 規範其實就是以前的 Swagger 規範，它是一種 REST API 的描述格式，透過既定的規範來描述文件介面，它是業界真正的 API 文件標準，可以透過 YAML 或者 JSON 來描述。它包括如下內容：

介面(/users)和每個介面的操作(GET /users，POST /users)
輸入引數和響應內容
認證方法
一些必要的聯絡資訊、license 等。
關於 OpenAPI 的更多內容，感興趣的小夥伴可以在 GitHub 上檢視：

以前在使用 2.9.2 這個版本的時候，一般來說我們可能需要新增如下兩個依賴：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

這兩個，一個用來生成介面文件(JSON 資料)，另一個用來展示將 JSON 視覺化。

在 3.0 版本中，我們不需要這麼麻煩了，一個 starter 就可以搞定：

<dependency> 
    <groupid>io.springfox</groupid>
    <artifactid>springfox-boot-starter</artifactid>
    <version>3.0.0</version>
</dependency>

和 Spring Boot 中的其他 starter 一樣，springfox-boot-starter 依賴可以實現零配置以及自動配置支援。也就是說，如果你沒有其他特殊需求，加一個這個依賴就行了，介面文件就自動生成了。

3.0 中的介面地址也和之前有所不同，以前在 2.9.2 中我們主要訪問兩個地址：

文件介面地址：
文件頁面地址：
現在在 3.0 中，這兩個地址也發生了變化：

文件介面地址：
文件頁面地址：
特別是文件頁面地址，如果用了 3.0，而去訪問之前的頁面，會報 404。

註解舊的註解還可以繼續使用，不過在 3.0 中還提供了一些其他註解。

例如我們可以使用 @EnableOpenApi 代替以前舊版本中的 @EnableSwagger2。

話是這麼說，不過鬆哥在實際體驗中，感覺 @EnableOpenApi 註解的功能不明顯，加不加都行。翻了下原始碼，@EnableOpenApi 註解主要功能是為了匯入 OpenApiDocumentationConfiguration 配置類，如下：

@Retention(value = java.lang.annotation.RetentionPolicy.RUNTIME) 
@Target(value = {java.lang.annotation.ElementType.TYPE}) 
@Documented 
@Import(OpenApiDocumentationConfiguration.class) 
public @interface EnableOpenApi { 
}

然後我又看了下自動化配置類 OpenApiAutoConfiguration，如下：

@Configuration 
@EnableConfigurationProperties(SpringfoxConfigurationProperties.class) 
@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true) 
@Import({ 
    OpenApiDocumentationConfiguration.class, 
    SpringDataRestConfiguration.class, 
    BeanValidatorPluginsConfiguration.class, 
    Swagger2DocumentationConfiguration.class, 
    SwaggerUiWebFluxConfiguration.class, 
    SwaggerUiWebMvcConfiguration.class 
}) 
@AutoConfigureAfter({ WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class, 
    HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class }) 
public class OpenApiAutoConfiguration { 
 
}

可以看到，自動化配置類裡邊也匯入了 OpenApiDocumentationConfiguration。

所以在正常情況下，實際上不需要新增 @EnableOpenApi 註解。

根據 OpenApiAutoConfiguration 上的 @ConditionalOnProperty 條件註解中的定義，我們發現，如果在 application.properties 中設定 springfox.documentation.enabled=false，即關閉了 swagger 功能，此時自動化配置類就不執行了，這個時候可以透過 @EnableOpenApi 註解匯入 OpenApiDocumentationConfiguration 配置類。技術上來說邏輯是這樣，不過應用中暫未發現這樣的需求(即在 application.properties 中關閉 swagger，再透過 @EnableOpenApi 註解開啟)。