當多終端（WEB/移動端）需要公用業務邏輯時，一般會構建 RESTful 風格的服務提供給多終端使用。
為了減少與對應終端開發團隊頻繁溝通成本，剛開始我們會創建一份 RESTful API 文檔來記錄所有接口細節。
但隨着項目推進，這樣做所暴露出來的問題也越來越嚴重。
a. 接口眾多，細節復雜（需考慮不同的 HTTP 請求類型、HTTP 頭部信息、HTTP 請求內容..），高質量地創建這份文檔本身就是件非常吃力的事。
b. 不斷修改接口實現必須同步修改接口文檔，而文檔與代碼又處於兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致不一致現象。
基於此，項目組在早些時間引入了 Swagger，經過幾個項目的沉淀，確實起到了很不錯的效果。
Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。
服務的方法、參數、模型緊密集成到服務器端的代碼，讓維護文檔和調整代碼融為一體，使 API 始終保持同步。
本文主要描述 Swagger 與 SpringMVC 的集成過程以及遇到的一些問題，權當拋磚引玉只用，具體項目具體分析。
1. Maven 依賴和最簡配置
<!--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 配置：
<!-- 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 配置類：
@Configuration @EnableSwagger2 public 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 文檔資源，使用方式：
@Api(description = "用戶管理")
@ApiOperation：注解在方法上，說明方法的作用，每一個url資源的定義,使用方式：
@ApiOperation(value = "獲取所有用戶列表")
@ApiParam、@ApiImplicitParam：注解到參數上，說明該參數作用，使用方式：
@ApiParam(value = "用戶ID") String userId
上述都為最簡配置，構建清晰的 API 文檔已足夠，當然還有很豐富的注解，知道有就行了。
@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 方法，在配置類中統一定義忽略的參數類型即可，這樣就方便很多。
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)
@ApiModelProperty(hidden = true) private String uuid; @ApiModelProperty("姓名") private String name; @ApiModelProperty("密碼") private String passwd;
c. @Api 注解中的 tags 值不支持中文，中文值會導致無法展開；
Swagger 有很豐富的工具，還能做很多事，本文所述只是能讓你迅速了解它、使用它、有需要多查資料、多翻博客。