Swagger3.0有哪些新特性

這篇文章主要講解了“Swagger3.0有哪些新特性”，文中的講解內(nèi)容簡單清晰，易于學習與理解，下面請大家跟著小編的思路慢慢深入，一起來研究和學習“Swagger3.0有哪些新特性”吧！

支持 OpenAPI

什么是 OpenAPI?

OpenAPI 規(guī)范其實就是以前的 Swagger 規(guī)范，它是一種 REST API 的描述格式，通過既定的規(guī)范來描述文檔接口，它是業(yè)界真正的 API  文檔標準，可以通過 YAML 或者 JSON 來描述。它包括如下內(nèi)容：

• 接口(/users)和每個接口的操作(GET /users，POST /users)

• 輸入?yún)?shù)和響應(yīng)內(nèi)容

• 認證方法

• 一些必要的聯(lián)系信息、license 等。

關(guān)于 OpenAPI 的更多內(nèi)容，感興趣的小伙伴可以在 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 數(shù)據(jù))，另一個用來展示將 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  依賴可以實現(xiàn)零配置以及自動配置支持。也就是說，如果你沒有其他特殊需求，加一個這個依賴就行了，接口文檔就自動生成了。

接口地址

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

• 文檔接口地址：http://localhost:8080/v2/api-docs

• 文檔頁面地址：http://localhost:8080/swagger-ui.html

現(xiàn)在在 3.0 中，這兩個地址也發(fā)生了變化：

• 文檔接口地址：http://localhost:8080/v3/api-docs

• 文檔頁面地址：http://localhost:8080/swagger-ui/index.html

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

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

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

話是這么說，不過松哥在實際體驗中，感覺 @EnableOpenApi 注解的功能不明顯，加不加都行。翻了下源碼，@EnableOpenApi  注解主要功能是為了導(dǎo)入 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 {  }

可以看到，自動化配置類里邊也導(dǎo)入了 OpenApiDocumentationConfiguration。

所以在正常情況下，實際上不需要添加 @EnableOpenApi 注解。

根據(jù) OpenApiAutoConfiguration 上的 @ConditionalOnProperty 條件注解中的定義，我們發(fā)現(xiàn)，如果在  application.properties 中設(shè)置 springfox.documentation.enabled=false，即關(guān)閉了 swagger  功能，此時自動化配置類就不執(zhí)行了，這個時候可以通過 @EnableOpenApi 注解導(dǎo)入 OpenApiDocumentationConfiguration  配置類。技術(shù)上來說邏輯是這樣，不過應(yīng)用中暫未發(fā)現(xiàn)這樣的需求(即在 application.properties 中關(guān)閉 swagger，再通過  @EnableOpenApi 注解開啟)。

感謝各位的閱讀，以上就是“Swagger3.0有哪些新特性”的內(nèi)容了，經(jīng)過本文的學習后，相信大家對Swagger3.0有哪些新特性這一問題有了更深刻的體會，具體使用情況還需要大家實踐驗證。這里是億速云，小編將為大家推送更多相關(guān)知識點的文章，歡迎關(guān)注！