Spring MVC利用Swagger2如何構(gòu)建動態(tài)RESTful API詳解

更新時間：2017年10月22日 10:40:13 作者：Orson

這篇文章主要給大家介紹了關于在Spring MVC中利用Swagger2如何構(gòu)建動態(tài)RESTful API的相關資料，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面來一起學習學習吧。

前言

本文主要給大家介紹了關于Spring MVC用Swagger2構(gòu)建動態(tài)RESTful API的相關內(nèi)容，當多終端（WEB/移動端）需要公用業(yè)務邏輯時，一般會構(gòu)建 RESTful 風格的服務提供給多終端使用。

為了減少與對應終端開發(fā)團隊頻繁溝通成本，剛開始我們會創(chuàng)建一份 RESTful API 文檔來記錄所有接口細節(jié)。

但隨著項目推進，這樣做所暴露出來的問題也越來越嚴重。

a. 接口眾多，細節(jié)復雜（需考慮不同的 HTTP 請求類型、HTTP 頭部信息、HTTP 請求內(nèi)容..），高質(zhì)量地創(chuàng)建這份文檔本身就是件非常吃力的事。

b. 不斷修改接口實現(xiàn)必須同步修改接口文檔，而文檔與代碼又處于兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致不一致現(xiàn)象。

基于此，項目組在早些時間引入了 Swagger，經(jīng)過幾個項目的沉淀，確實起到了很不錯的效果。

Swagger 是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風格的 Web 服務。

服務的方法、參數(shù)、模型緊密集成到服務器端的代碼，讓維護文檔和調(diào)整代碼融為一體，使 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 靜態(tài)資源交由 spring 管理映射(springfox-swagger-ui.jar 為靜態(tài)資源包)-->
 <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 處理靜態(tài)資源，并添加一些有用的附加值功能。

a. <mvc:resources /> 允許靜態(tài)資源放在任何地方，如 WEB-INF 目錄下、類路徑下等，完全打破了靜態(tài)資源只能放在 Web 容器的根路徑下這個限制。

b. <mvc:resources /> 依據(jù)當前著名的 Page Speed、YSlow 等瀏覽器優(yōu)化原則對靜態(tài)資源提供優(yōu)化。

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. 服務注解配置實踐

經(jīng)過上述的操作，其實 Swagger 已經(jīng)集成完畢，在項目開發(fā)推進中，只需在對應 RESTful 服務上添加對應注解即可。

@Api：注解在類上，說明該類的作用?？梢詷擞浺粋€ Controller 類做為 swagger 文檔資源，使用方式：

@Api(description = "用戶管理")

@ApiOperation：注解在方法上，說明方法的作用，每一個url資源的定義,使用方式：

@ApiOperation(value = "獲取所有用戶列表")

@ApiParam、@ApiImplicitParam：注解到參數(shù)上，說明該參數(shù)作用，使用方式：

@ApiParam(value = "用戶ID") String userId

上述都為最簡配置，構(gòu)建清晰的 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) {

 }
}

在項目后續(xù)使用中遇到的一些問題：

a. 一些方法入?yún)⑷?HttpServletRequest、HttpServletResponse、HttpSession、ModelMap 等等，這些參數(shù)在生成 API 文檔時是無意義的，Swagger 正確的配置方式？

剛開始時使用 @ApiParam(hidden = true) 注解這些參數(shù)，方法繁多的時候，這些類型的入?yún)⒍家獙懸槐?，使用起來很冗余?/p>

在 API 中發(fā)現(xiàn) Docket 對象有 ignoredParameterTypes 方法，在配置類中統(tǒng)一定義忽略的參數(shù)類型即可，這樣就方便很多。

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. 當請求的參數(shù)為封裝的對象時，怎樣進行注解？對象中的屬性怎樣注解？怎樣屏蔽對象中的莫個屬性？

請求的參數(shù)為對象時，使用Spring @ModelAttribute 注解對應對象，對象當中的屬性使用 @ApiModelProperty ，屏蔽莫個屬性 @ApiModelProperty(hidden = true)

@ApiModelProperty(hidden = true)
 private String uuid;

 @ApiModelProperty("姓名")
 private String name;

 @ApiModelProperty("密碼")
 private String passwd;