在多人協(xié)作的開發(fā)過程中，API文檔不僅可以減少等待右蹦，也能保證開發(fā)的持續(xù)進(jìn)行举瑰。有一些單元測(cè)試框架可以生成API文檔，而Swagger可以在不寫單元測(cè)試的情況下生成在線的API頁(yè)面换况，并且可以直接在頁(yè)面進(jìn)行API調(diào)試职辨。
- 引入需要的依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
- 在啟動(dòng)類也就是XXXApplication類的同級(jí)目錄下創(chuàng)建Swagger2類，作為配置類
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.com.wenyi.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Brand Love APIS")
.description("基于指數(shù)數(shù)據(jù)的品牌趨勢(shì)分析工具")
.version("1.0.3")
.build();
}
}
通過@Configuration我們標(biāo)記此類為配置類戈二，會(huì)在SpringBoot項(xiàng)目啟動(dòng)的時(shí)候加載舒裤，@EnableSwagger2用來啟動(dòng)Swagger。
實(shí)際上我們已經(jīng)完成了對(duì)Swagger的配置觉吭，Swagger會(huì)自動(dòng)掃描我們配置的cn.com.wenyi.controller包下的接口自動(dòng)生成接口文檔腾供。
其地址為：http://localhost:8080/swagger-ui.html
3.接下來我們可以對(duì)我們的接口參數(shù)進(jìn)一步說明：
#在Controller上使用@Api會(huì)生成這個(gè)Controller的整體描述
@Api(value = "Base Index API", description = "基礎(chǔ)指數(shù)數(shù)據(jù)")
#在具體方法上使用@ApiOperation可以生成接口的描述
@ApiOperation(value = "回溯數(shù)據(jù)", notes = "回溯品牌歷史指數(shù)數(shù)據(jù)")
#在方法上使用@ApiImplicitParam可以增加對(duì)參數(shù)等的描述
@ApiImplicitParam(name = "brand", value = "品牌名稱", required = true, dataType = "String", paramType = "query")
其他更多操作我們可以查看網(wǎng)上的文章晚上我們的接口文檔。
總結(jié)
Swagger生成的文檔在我看來并不精美鲜滩，但是對(duì)于多人協(xié)作開發(fā)來說的確是方便了很多伴鳖。
其次Swagger可以直接在頁(yè)面進(jìn)行請(qǐng)求操作大大減少了需要使用額外工具來模擬請(qǐng)求的開銷。
并且是由開發(fā)者直接維護(hù)請(qǐng)求參數(shù)等绒北，避免模擬請(qǐng)求傳錯(cuò)參數(shù)造成額外沒必要的溝通黎侈。
最后Swagger在我看來最大的弊端除了不夠精美以外，就是浸入式的寫法會(huì)造成代碼臃腫闷游，且在移除時(shí)，需要?jiǎng)h除大量代碼贴汪。而這種做法顯得有些不優(yōu)雅脐往。
