背景
本人自己使用的swagger2.0，鑑於顏值和OpenAPI規範，就想體驗下，後續再補充各種情況的demo。
一、什麼是swagger？
OpenAPI規範（OpenAPI Specification 簡稱OAS）是Linux基金會的一個項目，試圖通過定義一種用來描述API格式或API定義的語言，來規範RESTful服務開發過程。目前V3.0版本的OpenAPI規範（也就是SwaggerV2.0規範）已經發布並開源在github上。即swagger2.0是基於 The Apache License, Version 2.0許可的OAS3.0實現。
二、爲什麼要用Swagger管理項目（Swagger特性）？
Swagger tools提供了多個模塊用戶構建文檔，不同的模塊擁有不同的作用，主模塊如下：
1、設計接口
Swagger Editor：一個強大的編輯器中設計新的api或編輯現有的api，它可以直觀地呈現您的狂妄定義，並提供實時的錯誤反饋。可以支持json和yaml（一般使用yaml）格式的數據類型。如下圖：
2、構建
通過生成服務器存根和來自swagger的規範的客戶端sdk，構建並啓用OAS/Swagger 的可編程語言。
3、Swagger UI
Swagger需要在後臺配置對於接口的相關信息並使用註解的方式將信息通過Swagger UI進行展示，自動生成了用於視覺交互的OAS規範中描述的所有文檔，所以優點在於實時，減少溝通；缺點也在於使用註解的方式，過深的與代碼本身交互。
三、Swagger UI2.0的實現
1、引入maven依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
2、Swagger配置及靜態配置
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.async.DeferredResult;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/*
* Restful API 訪問路徑:
* http://IP:port/{context-path}/swagger-ui.html
* eg:http://localhost:8080/vrworldapi/api/swagger-ui.html
*/
@Component
@EnableSwagger2
@ComponentScan(basePackages = {"gevek.vr.controller"})
@Configuration
public class RestApiConfig extends WebMvcConfigurationSupport{
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
/*.groupName("用戶數據模塊")*/
.genericModelSubstitutes(DeferredResult.class)
// .genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(false)
.select()
.apis(RequestHandlerSelectors.basePackage("gevek.vr.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXXXRESTful APIs")
.termsOfServiceUrl("http://www.lfly.com")
.contact("XXXX")
.version("1.1")
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.build();
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
靜態配置說明：靜態文件swagger-ui的設置路徑參見下圖：
3、使用註解配置Controller
核心部分，需要爲每一個接口配置OpenAPI規範的所有信息。常用註解如下（具體配置參數參見官網）：
@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該註解忽略這個API
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
4、效果
具體每個接口參數信息如下：
四、Swagger UI的擴展
基於Swagger的註解將API個路徑、描述、參數、返回值、異常狀況等進行描述，swagger UI 模塊僅僅是一個前端渲染框架。由於swagger默認的UI的樣式雖然基於其他方式的API文件已經非常不錯了，但是頁面任然不是特別的美觀。於是出現了swagger-ui-layer和Swagger-Bootstrap-UI等框架，其本質僅僅是一個更友好和美觀的前端UI界面的實現，解析的數據來源於 /v2/api-docs，而底層依然依賴於swagger的註解功能。
1、swagger-ui-layer
在pom.xml中引入swagger 和 swagger-ui-layer和依賴，其他與使用swagger2一致，maven依賴如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>0.0.2</version>
</dependency>
需要注意的一點是 swagger api 的默認地址是/v2/api-docs 所以swagger-ui-layer也讀取的是默認地址， 所以在new Docket()的時候不能指定group參數，否則 swagger api 的地址會在後面加入group的參數導致swagger-ui-layer不能正確請求到數據。即使用自定義後的ui不能使用分組功能將同一類型的api進行拆分。
swagger-ui-layer 的默認訪問地址是 http://${host}😒{port}/docs.html，而美化的界面如下：
和
2、Swagger-Bootstrap-UI
Swagger-Bootstrap-UI與swagger-ui-layer大致相同，需要引入的依賴如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
swagger-bootstrap-ui默認訪問地址是：http://${host}😒{port}/doc.html。
需要注意：swagger封裝給出的請求地址默認是/v2/api-docs,所以swagger-bootstrap-ui調用後臺也是/v2/api-docs,不能帶後綴,且需返回json格式數據,框架如果是spring boot的可以不用修改,直接使用,如果是Spring MVC在web.xml中配置了DispatcherServlet,則需要追加一個url匹配規則,如下：
<servlet>
<servlet-name>cmsMvc</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:config/spring.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<!--默認配置,.htm|.do|.json等等配置-->
<servlet-mapping>
<servlet-name>cmsMvc</servlet-name>
<url-pattern>*.htm</url-pattern>
</servlet-mapping>
<!-- 配置swagger-bootstrap-ui的url請求路徑-->
<servlet-mapping>
<servlet-name>cmsMvc</servlet-name>
<url-pattern>/v2/api-docs</url-pattern>
</servlet-mapping>
效果圖如下：
————————————————
原文鏈接：https://blog.csdn.net/it_lihongmin/article/details/78829163