松哥原創的 Spring Boot 視頻教程已經殺青,感興趣的小夥伴戳這裏-->Spring Boot+Vue+微人事視頻教程
在社區的推動下,Springfox3.0 去年 7 月份就發佈了,最近終於得空和小夥伴們聊一聊新版本的新變化。這次的版本升級估計小夥伴們都翹首以待好久了,畢竟上一次發版已經是兩年前的事情了。
新版本還是有很多好玩的地方,我們一起來看下。
支持 OpenAPI
什麼是 OpenAPI?
OpenAPI 規範其實就是以前的 Swagger 規範,它是一種 REST API 的描述格式,通過既定的規範來描述文檔接口,它是業界真正的 API 文檔標準,可以通過 YAML 或者 JSON 來描述。它包括如下內容:
-
接口(/users)和每個接口的操作(GET /users,POST /users) -
輸入參數和響應內容 -
認證方法 -
一些必要的聯繫信息、license 等。
關於 OpenAPI 的更多內容,感興趣的小夥伴可以在 GitHub 上查看:https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
依賴
以前在使用 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 中我們主要訪問兩個地址:
-
文檔接口地址:http://localhost:8080/v2/api-docs -
文檔頁面地址:http://localhost:8080/swagger-ui.html
現在在 3.0 中,這兩個地址也發生了變化:
-
文檔接口地址:http://localhost:8080/v3/api-docs -
文檔頁面地址:http://localhost:8080/swagger-ui/index.html
特別是文檔頁面地址,如果用了 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 註解開啓)。
對於 @EnableOpenApi 註解的使用場景,小夥伴們要是有自己的見解,歡迎留言討論。
另外,以前我們用的 @ApiResponses/@ApiResponse 註解,在 3.0 中名字沒變,但是所在的包變了,小夥伴們使用時注意導包問題哦。
另外,我們之前用的 @ApiOperation 註解在 3.0 中可以使用 @Operation 代替。
另外還有一些新註解如 @Parameter、Parameters、@Schema 等,松哥嘗試了下,感覺不太好用,不如舊的用的舒服,這些新註解小夥伴們可以自行嘗試下。
好啦,今天主要和小夥伴們分享了 Swagger3.0 帶來的一些新變化,如果還沒用過 Swagger,可以在公衆號後臺回覆 666,有一個松哥原創的 Spring Boot 入門教程,裏邊有講 Swagger 的用法。
精彩文章推薦:
喜歡就點個"在看"唄^_^
本文分享自微信公衆號 - 江南一點雨(a_javaboy)。
如有侵權,請聯繫 [email protected] 刪除。
本文參與“OSC源創計劃”,歡迎正在閱讀的你也加入,一起分享。