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

前言

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

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

但隨著項(xiàng)目推進(jìn)，這樣做所暴露出來(lái)的問(wèn)題也越來(lái)越嚴(yán)重。

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

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

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

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

服務(wù)的方法、參數(shù)、模型緊密集成到服務(wù)器端的代碼，讓維護(hù)文檔和調(diào)整代碼融為一體，使 API 始終保持同步。

本文主要描述 Swagger 與 SpringMVC 的集成過(guò)程以及遇到的一些問(wèn)題，權(quán)當(dāng)拋磚引玉只用，具體項(xiàng)目具體分析。

1. Maven 依賴和最簡(jiǎn)配置

<!--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 容器的根路徑下這個(gè)限制。

      b. <mvc:resources /> 依據(jù)當(dāng)前著名的 Page Speed、YSlow 等瀏覽器優(yōu)化原則對(duì)靜態(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();
 }
}

對(duì)于生成哪些請(qǐng)求方法 API ？ Swagger 提供了 RequestHandlerSelectors 對(duì)象的以下方法進(jìn)行限制范圍：

2. 服務(wù)注解配置實(shí)踐

經(jīng)過(guò)上述的操作，其實(shí) Swagger 已經(jīng)集成完畢，在項(xiàng)目開發(fā)推進(jìn)中，只需在對(duì)應(yīng) RESTful 服務(wù)上添加對(duì)應(yīng)注解即可。

      @Api：注解在類上，說(shuō)明該類的作用?？梢詷?biāo)記一個(gè) Controller 類做為 swagger  文檔資源，使用方式：

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

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

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

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

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

上述都為最簡(jiǎn)配置，構(gòu)建清晰的 API  文檔已足夠，當(dāng)然還有很豐富的注解，知道有就行了。

@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) {

 }
}

在項(xiàng)目后續(xù)使用中遇到的一些問(wèn)題：

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

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

   在 API 中發(fā)現(xiàn) Docket 對(duì)象有 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. 當(dāng)請(qǐng)求的參數(shù)為封裝的對(duì)象時(shí)，怎樣進(jìn)行注解？對(duì)象中的屬性怎樣注解？怎樣屏蔽對(duì)象中的莫個(gè)屬性？

   請(qǐng)求的參數(shù)為對(duì)象時(shí)，使用Spring @ModelAttribute 注解對(duì)應(yīng)對(duì)象，對(duì)象當(dāng)中的屬性使用 @ApiModelProperty ，屏蔽莫個(gè)屬性 @ApiModelProperty(hidden = true)

@ApiModelProperty(hidden = true)
 private String uuid;

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

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

Swagger 有很豐富的工具，還能做很多事，本文所述只是能讓你迅速了解它、使用它、有需要多查資料、多翻博客。

總結(jié)

以上就是這篇文章的全部?jī)?nèi)容了，本文還有許多不足，希望本文的內(nèi)容對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，如果有疑問(wèn)大家可以留言交流，謝謝大家對(duì)億速云的支持。