前言
本文主要給大家介紹了關于Spring MVC用Swagger2構建動態RESTful API的相關內容，當多終端（WEB/移動端）需要公用業務邏輯時，一般會構建 RESTful 風格的服務提供給多終端使用。
為了減少與對應終端開發團隊頻繁溝通成本，剛開始我們會創建一份 RESTful API 文檔來記錄所有接口細節。
但隨著項目推進，這樣做所暴露出來的問題也越來越嚴重。
a. 接口眾多，細節復雜（需考慮不同的 HTTP 請求類型、HTTP 頭部信息、HTTP 請求內容..），高質量地創建這份文檔本身就是件非常吃力的事。
b. 不斷修改接口實現必須同步修改接口文檔，而文檔與代碼又處于兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致不一致現象。
基于此，項目組在早些時間引入了 Swagger，經過幾個項目的沉淀，確實起到了很不錯的效果。
Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。
服務的方法、參數、模型緊密集成到服務器端的代碼，讓維護文檔和調整代碼融為一體，使 API 始終保持同步。
本文主要描述 Swagger 與 SpringMVC 的集成過程以及遇到的一些問題，權當拋磚引玉只用，具體項目具體分析。
1. Maven 依賴和最簡配置
|
1
2
3
4
5
6
7
8
9
10
11
12
|
<!--restfull APi swagger2--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger.version}</version> </dependency> |
Spring-Context Swagger 配置：
|
1
2
3
4
5
6
|
<!-- swagger2 配置類--> <bean id="config" class="com.rambo.spm.core.config.SwaggerConfig"/> <!-- swagger2 靜態資源交由 spring 管理映射(springfox-swagger-ui.jar 為靜態資源包)--> <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/> |
<mvc:resources /> 由 Spring MVC 處理靜態資源，并添加一些有用的附加值功能。
a. <mvc:resources /> 允許靜態資源放在任何地方，如 WEB-INF 目錄下、類路徑下等，完全打破了靜態資源只能放在 Web 容器的根路徑下這個限制。
b. <mvc:resources /> 依據當前著名的 Page Speed、YSlow 等瀏覽器優化原則對靜態資源提供優化。
SwaggerConfig 配置類：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder(); apiInfoBuilder.title("SPM Doc"); apiInfoBuilder.description("SPM Api文檔"); apiInfoBuilder.contact(new Contact("orson", "https://www.cnblogs.com/", "")); apiInfoBuilder.version("2.0"); return apiInfoBuilder.build(); }} |
對于生成哪些請求方法 API ？ Swagger 提供了 RequestHandlerSelectors 對象的以下方法進行限制范圍：
2. 服務注解配置實踐
經過上述的操作，其實 Swagger 已經集成完畢，在項目開發推進中，只需在對應 RESTful 服務上添加對應注解即可。
@Api：注解在類上，說明該類的作用。可以標記一個 Controller 類做為 swagger 文檔資源，使用方式：
|
1
|
@Api(description = "用戶管理") |
@ApiOperation：注解在方法上，說明方法的作用，每一個url資源的定義,使用方式：
|
1
|
@ApiOperation(value = "獲取所有用戶列表") |
@ApiParam、@ApiImplicitParam：注解到參數上，說明該參數作用，使用方式：
|
1
|
@ApiParam(value = "用戶ID") String userId |
上述都為最簡配置，構建清晰的 API 文檔已足夠，當然還有很豐富的注解，知道有就行了。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
@RestController@Api(description = "用戶管理")public class UserRestController extends BaseController { @Autowired private SysUserService sysUserService; @GetMapping("r/user/get") @ApiOperation(value = "獲取特定用戶詳情") public Object getUser(ModelMap modelMap, @ApiParam(value = "用戶ID") String userId) { } @PostMapping("r/user/add") @ApiOperation(value = "添加用戶") public Object addUser(ModelMap modelMap, @ModelAttribute @Valid SysUser user, BindingResult result) { }} |
在項目后續使用中遇到的一些問題：
a. 一些方法入參如 HttpServletRequest、HttpServletResponse、HttpSession、ModelMap 等等，這些參數在生成 API 文檔時是無意義的，Swagger 正確的配置方式？
剛開始時使用 @ApiParam(hidden = true) 注解這些參數，方法繁多的時候，這些類型的入參都要寫一遍，使用起來很冗余。
在 API 中發現 Docket 對象有 ignoredParameterTypes 方法，在配置類中統一定義忽略的參數類型即可，這樣就方便很多。
|
1
2
3
4
5
6
7
8
9
|
public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .ignoredParameterTypes(ModelMap.class, HttpServletRequest.class,HttpServletResponse.class, BindingResult.class) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } |
b. 當請求的參數為封裝的對象時，怎樣進行注解？對象中的屬性怎樣注解？怎樣屏蔽對象中的莫個屬性？
請求的參數為對象時，使用Spring @ModelAttribute 注解對應對象，對象當中的屬性使用 @ApiModelProperty ，屏蔽莫個屬性 @ApiModelProperty(hidden = true)
|
1
2
3
4
5
6
7
8
|
@ApiModelProperty(hidden = true) private String uuid; @ApiModelProperty("姓名") private String name; @ApiModelProperty("密碼") private String passwd; |
Swagger 有很豐富的工具，還能做很多事，本文所述只是能讓你迅速了解它、使用它、有需要多查資料、多翻博客。
總結
以上就是這篇文章的全部內容了，本文還有許多不足，希望本文的內容對大家的學習或者工作具有一定的參考學習價值，如果有疑問大家可以留言交流，謝謝大家對服務器之家的支持。
原文鏈接：http://www.cnblogs.com/java-class/p/7544610.html
