Spring Boot 2.x （十二）：Swagger2的正確玩兒法

SpringBoot Swagger · 發表 2019-03-08 08:42:00

摘要： Swagger2簡介簡單的來說，Swagger2的誕生就是為了解決前後端開發人員進行交流的時候 API文件難以維護的痛點，它可以和我們的Java程式完美的結合在一起，並且可以與我們的另一開發利器Spring Boot來配合使用。開始使用第一步：匯入POM檔案 <...

Swagger2簡介

簡單的來說，Swagger2的誕生就是為了解決前後端開發人員進行交流的時候 API文件難以維護 的痛點，它可以和我們的Java程式完美的結合在一起，並且可以與我們的另一開發利器Spring Boot來配合使用。

開始使用

第一步：匯入POM檔案

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency> 

<!-- 這裡使用 swagger-bootstrap-ui 替代了原有醜陋的ui，拯救處女座~ -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.0</version>
</dependency>

#### 第二步：新增配置類

我們需要新增一個Swagger2Config 的配置類：

/**
 *Swagger2 配置類
 * @author vi
 * @since 2019/3/6 8:31 PM
 */
@Configuration
public class Swagger2Config {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("indi.viyoung.viboot.*"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("viboot-swagger2")//標題
.description("Restful-API-Doc") //描述
.termsOfServiceUrl("https://www.cnblogs.com/viyoung") //這裡配置的是服務網站，我寫的是我的部落格園站點~歡迎關注~
.contact(new Contact("Vi的技術部落格", "https://www.cnblogs.com/viyoung", "[email protected]")) // 三個引數依次是姓名，個人網站，郵箱
.version("1.0") //版本
.build();
}
}

第三步：在啟動類中新增配置

注意一定要記得新增 @EnableSwagger2 註解

/**
 * @author vi
 * @since 2019/3/6 6:35 PM
 */
@SpringBootApplication
@ComponentScan(value = "indi.viyoung.viboot.*")
@MapperScan(value = "indi.viyoung.viboot.swagger2.mapper")
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class ViBootSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(ViBootSwaggerApplication.class, args);
}
}

第四步：通過註解來完成API文件

1. @Api

註解名稱	註解屬性	作用域	屬性作用
`@Api`	tags	類	說明該類的作用
	value	類	說明該類的作用

舉個:chestnut:：

@Api(value = "使用者類控制器",tags="使用者類控制器")
public class UserController {
...
}

2 . @ApiOperation

註解名稱	註解屬性	作用域	屬性作用
`@ApiOperation()`	value	方法	描述方法作用
	notes	方法	提示內容
	tags	方法	分組

舉個:chestnut:：

@ApiOperation(value = "獲取使用者列表",notes = "獲取使用者列表")
public List<User> get() {
...
}

3. @ApiParam

註解名稱	註解屬性	作用域	屬性作用
`@ApiParam()`	name	方法引數	引數名
	value	方法引數	引數說明
	required	方法引數	是否必填

舉個:chestnut:：

@ApiOperation(value="獲取使用者詳細資訊", notes="根據url的id來獲取使用者詳細資訊")
public User get(@ApiParam(name="id",value="使用者id",required=true) Long id) {
log.info("GET..{}...方法執行。。。",id);
return userService.getById(id);
}

4. @ApiModel && @ApiModelProperty

註解名稱	註解屬性	作用域	屬性作用
`@ApiModel()`	value	類	物件名
	description	類	描述
`@ApiModelProperty()`	value	方法	欄位說明
	name	方法	屬性名
	dataType	方法	屬性型別
	required	方法	是否必填
	example	方法	舉例
	hidden	方法	隱藏

舉個:chestnut:：

@ApiModel(value="user物件",description="使用者物件user")
public class User implements Serializable {

private static final long serialVersionUID = 1L;

@TableId(value = "id", type = IdType.AUTO)
@ApiModelProperty(value = "使用者ID",example = "1000001",hidden=true)
private Long id;

@ApiModelProperty(value="使用者名稱",required = true,dataType = "String")
private String userName;

@ApiModelProperty(value = "密碼")
private String password;
}

5. @ApiImplicitParam && @ApiImplicitParams

@ApiImplicitParam`可以單個用於方法至上，多個引數的話可以把`@ApiImplicitParam`放到`@ApiImplicitParams`中，這裡只羅列`@ApiImplicitParam`的屬性：

註解名稱	註解屬性	作用域	屬性作用
`@ApiImplicitParam()`	value	方法	引數說明
	name	方法	引數名
	dataType	方法	資料型別
	paramType	方法	引數型別
	example	方法	舉例

舉個:chestnut:：

@ApiImplicitParams({
@ApiImplicitParam(name = "user", value = "使用者實體user", required = true, dataType = "User")
})
public void put(User user) {
userService.updateById(user);
log.info("PUT方法執行。。。");
}

這裡需要注意一點，我們並沒有在註解中寫圖中圈中的兩個引數，這個是去讀取了我們剛剛為 User 類的註解，並將使用者名稱設定為必填！