SpringBoot整合Swagger2實例方法

原創

2019-06-21 17:03

在本篇文章裏小編給大家整合了關於SpringBoot整合Swagger2的相關知識點內容，有興趣的朋友們學習下。

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

首先需要在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註解，表明這是一個配置類，同時開啓Swagger。如下的信息可以根據具體情況修改。

@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("用戶信息相關")
      //服務條款網址
      .termsOfServiceUrl("https://baidu.com")
      .version("1.0")
      .contact(new Contact("NWSL", "http://baidu.com", "[email protected]"))
      .build();
}

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

接下來我們需要在方法上添加註解了，如下所示，@ApiOperation、@ApiImplicitParams、@ApiImplicitParam的作用如下圖所示。@ApiResponses：用在請求的方法上，表示一組響@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息。

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

@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"就可以省略了，寫上了反而在生成的文檔調用的時候出錯。

接下來我們介紹傳實體類參數的註解怎麼寫，要使用到@ApiModel、@ApiModelProperty，具體的用法如下圖所示。在接收參數的實體類上我們需要添加這兩個註解，如下圖所示。

接口上註解寫完之後，我們啓動服務，然後打開swagger的UI頁面，注意8091端口是我本機服務啓動的端口，請求的地址如下圖所示。我們可以看到每個Controller類都生成了文檔，UserController我們增加了類的註釋。

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