注： 主要記錄SpringBoot中使用Swagger2的步驟；
1. 引入依賴
引入maven依賴：
<!--Swagger2 dependency-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
2. 編寫配置類
@Configuration
@EnableSwagger2
public class SwaggerConfigurer {
@Bean
public TypeResolver typeResolver() {
return new TypeResolver();
}
@Bean
@Autowired
public Docket createRestApi(TypeResolver typeResolver) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.xxx.portal.controller")).paths(PathSelectors.any()).build();
}
// 添加應用、服務信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("Swagger2Test").contact(new Contact("Your name",
"Your Service's url",
"Your email")).version("2.0").build();
}
}
注：
title：即Swagger頁面上的標題（非標籤標題），建議使用應用名字；Contact("name", "url", "email")：表示相關信息；version：表示當服務版本，根據自己應用的版本填寫即可；basePackage：表示Swagger需要掃描的包註解，一定要寫對，否則打開Swagger頁面將會爲空【重要】；
3. 使用Swagger標籤
只記錄幾個常用標籤：
@Api(tag=..., description=...)：主要打在Controller上面，tag是String[]，value是String，比如@Api(tags = "Activity", description = "活動相關")；@ApiOperation：主要用於Controller中具體的方法上（準確點說應該是一個內部ttp請求的方法），用於說明這個RequestMapping的作用，比如@ApiOperation(name = "Activity Info", value = "獲取活動基本信息")，這個註解中也有tag（會單獨生成條Swagger記錄，不推薦使用這個屬性標籤）；@ApiImplicitParam：這個可以直接方法體上對傳入參數進行註解說明，不要求註解在傳入的參數上(相對於@ApiParam必須註解到對應的參數上更加靈活)，內部有幾個屬性：name：參數名（一定要和參數對應上）；value：參數含義說明；paramType：參數類型，可取值爲–"path"(url參數)、"query"(請求參數)、"body"(請求體參數)、"header"(頭部參數)、"form"(表單參數)；required：該參數是否必須，true/false；dataType：參數類型，可選值有–string、number（包含整數和浮點數，即包含integer）、integer、boolean、array、object；
@ApiImplicitParams：和上述註解對應的，類型爲ApiImplicitParam[]，用於對多個參數說明；
注：上述的@ApiImplicitParam註解中name屬性一定要和傳入的參數名一致，這裏的參數名是指和HTTP方法直接相關的參數，而不是經過序列化的後的參數名，比如：
@ApiOperation(value = "獲取活動相關的獎品列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "activity_id", value = "活動id", paramType = "path", required = true, dataType = "integer"),
@ApiImplicitParam(name = "activity_name", value = "活動名字", paramType = "query", required = true, dataType = "string")
})
@RequestMapping(value = "/{activity_id}/awards", method = RequestMethod.GET)
public GeneralResponse<List<AwardBean>> getActivityAwards(@PathVariable("activity_id") Integer activityId, @RequestParam("activity_name") String name) {
return new GeneralResponse<>(activityAwardService.listAward(activityId));
}
上述@ApiImplicitParam中的name屬性應該直接填寫URL中的activity_id和activity_name才能對應上，如果寫成序列化後的參數名activityId和name就不能對應上，會直接生成額外Swagger兩條的參數說明。
上述的標籤基本可以滿足需求了，但發現如果是傳入的參數是一個對象的時候，想對對象中的一些屬性做一些解釋說明的時候，發現可以在Controller中不要管他，只要在對應的對象上進行如下註解即可，如：
@ApiModel
public class ContributorBean {
/**
* 姓名
*/
@ApiModelProperty(name = "name", value = "貢獻者姓名", required = true)
private String name;
/**
* 文件id
*/
@ApiModelProperty(name = "fileIds", value = "貢獻文件的id", required = true)
private List<Long> fileIds;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public List<Long> getFileIds() {
return fileIds;
}
public void setFileIds(List<Long> fileIds) {
this.fileIds = fileIds;
}
}
然後再Controller中的方法體上直接使用@ApiImplicitParam註解指定上述類型的參數即可。
4. 啓動查看
啓動項目後，直接訪問http://localhost:8090/portal/swagger-ui.html項目地址即可，平心而論，個人覺的代碼耦合度太高，尤其是@ApiModel註解更是深入到了封裝的對象中。
注：自己實現了WebMvcConfigurer接口後，不能去重寫裏面的configureMessageConverters方法，否則可能導致無法數據無法正常序列化從而Swagger不能正常顯示；