在進(jìn)行軟件開發(fā)的時(shí)候免不了要寫接口文檔，這些文檔需要明確寫出接口的類型、請求的URL、傳參和返回值格式等信息，用于和前端交互或者提供給測試進(jìn)行接口測試。但是手寫文檔一方面帶給我們很大的工作量，另一方面如果接口有變更則需要頻繁修改并且發(fā)給相關(guān)的人，無形中增加了工作量。小編為大家介紹一個(gè)生成文檔的工具Swagger，上手簡單，學(xué)習(xí)成本低，非常適合開發(fā)SpringBoot項(xiàng)目，現(xiàn)在就跟著小編一起學(xué)習(xí)吧。

首先需要在pom文件中加入swagger2的依賴，依賴的jar包如下圖所示。

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.8.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.8.0</version>
</dependency>

編寫Swagger配置類Swagger2Config，在類上增加@Configuration和@EnableSwagger2注解，表明這是一個(gè)配置類，同時(shí)開啟Swagger。如下的信息可以根據(jù)具體情況修改。

@Bean
public Docket api() {
  return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()
      // 自行修改為自己的包路徑
      .apis(RequestHandlerSelectors.basePackage("com.spring.jpa.user"))
      .paths(PathSelectors.any())
      .build();
}

private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
      .title("swagger-api文檔")
      .description("用戶信息相關(guān)")
      //服務(wù)條款網(wǎng)址
      .termsOfServiceUrl("https://baidu.com")
      .version("1.0")
      .contact(new Contact("NWSL", "http://baidu.com", "111111@qq.com"))
      .build();
}

接下來我們需要在Controller層添加注解，@Api(value="/test1", tags="測試用戶接口模塊")， @Api這個(gè)注解是用在請求的類上，表示對類的說明，其中tags="說明該類的作用，可以在UI界面上看到的注解"，value="該參數(shù)沒什么意義，在UI界面上也看到，所以不需要配置"。該注解的使用如下圖所示。

接下來我們需要在方法上添加注解了，如下所示，@ApiOperation、@ApiImplicitParams、@ApiImplicitParam的作用如下圖所示。@ApiResponses：用在請求的方法上，表示一組響@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息。

在方法中的使用如下圖所示。

@ApiOperation(value="添加用戶信息", notes = "添加用戶信息")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "用戶姓名", required = true, dataType = "String",paramType = "query"),
    @ApiImplicitParam(name = "age", value = "用戶年齡", required = true,paramType = "query")
})

注意如果是Integer類型，那dataType = "Integer"就可以省略了，寫上了反而在生成的文檔調(diào)用的時(shí)候出錯(cuò)。

接下來我們介紹傳實(shí)體類參數(shù)的注解怎么寫，要使用到@ApiModel、@ApiModelProperty，具體的用法如下圖所示。在接收參數(shù)的實(shí)體類上我們需要添加這兩個(gè)注解，如下圖所示。

接口上注解寫完之后，我們啟動(dòng)服務(wù)，然后打開swagger的UI頁面，注意8091端口是我本機(jī)服務(wù)啟動(dòng)的端口，請求的地址如下圖所示。我們可以看到每個(gè)Controller類都生成了文檔，UserController我們增加了類的注釋。

接下來我們測試UserController中的接口，如下圖所示，生成了UserController所有的接口文檔，我們首先來看添加用戶接口，如下圖所示，為什么Integer類型的age字段，在生成的接口文檔中參數(shù)類型變成了ref呢？上文提到過的，在寫注解的時(shí)候，dataType = "Integer"要省略掉，不然會出現(xiàn)這個(gè)問題。正確的如下所示，可以看到age為Integer類型了。

我們可以看到在接口的右側(cè)有Try it out，點(diǎn)擊該按鈕進(jìn)入到調(diào)用頁面。在如下的頁面填寫完參數(shù)之后執(zhí)行Execute即可，還是age參數(shù)ref的問題，此時(shí)執(zhí)行會提示錯(cuò)誤，要把注釋中的Integer類型去掉，在執(zhí)行即可。

接下來我們看一個(gè)Get請求，這個(gè)請求不需要傳參，直接執(zhí)行即可，結(jié)果如下圖所示。我們可以看到Swagger生成的restful形式的接口文檔，非常方便調(diào)試。

接下來我們執(zhí)行update的接口，這是上面我們用實(shí)體類接收參數(shù)的方法，可以看到參數(shù)的例子，我們修改完參數(shù)值后執(zhí)行即可。以上swagger2與springboot就集成完了。

最新評論