Swagger
??Swagger號(hào)稱是史上最流行的、最好用的API接口文檔構(gòu)建工具，它支持多種語言包括Java在內(nèi)，本文僅關(guān)注如何使用Spring Boot來集成Swagger，更多關(guān)于Swagger的介紹可以查看以下幾個(gè)鏈接。
SpringFox
??SpringFox最初叫Swagger-SpringMVC，從字面意義上簡(jiǎn)單來理解是使用了SpringMVC來集成Swagger，后來演變成SpringFox這么一個(gè)項(xiàng)目(或組織)，SpringFox官網(wǎng)有這么一句：Automated JSON API documentation for API's built with Spring(針對(duì)Spring構(gòu)建的API的自動(dòng)化JSON API文檔)。好了，下來我們只需用SpringFox提供的三方庫來快速集成一下Spring Boot和Swagger。
1. 添加Maven依賴
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${latest version}</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${latest version}</version>
</dependency>
2. 開啟Swagger
??在Spring Boot啟動(dòng)類上添加@EnableSwagger2即可。
@SpringBootApplication
@EnableSwagger2 //開啟Swagger
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
3. 配置Swagger
??
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 這里是全局掃描有@Api注解得類，還可以掃描任意位置，指定包以及針對(duì)方法上的指定注解
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Title")
.description("Description")
.termsOfServiceUrl("")
.contact(new Contact("", "", ""))
.license("")
.licenseUrl("")
.version(" xxx ")
.build();
}
}
4. 運(yùn)行效果
??啟動(dòng)Spring Boot后，可以點(diǎn)擊查看(更改為你的本地地址) http://localhost:8080/swagger-ui.html#/ ，效果如下：
5. 常用注解
??Swagger的所有注解定義在io.swagger.annotations包下，下面列一些經(jīng)常用到的，未列舉出來的可以另行查閱說明：
| Swagger注解 | 簡(jiǎn)單說明 |
|---|---|
| @Api(tags = "xxx模塊說明") | 作用在模塊類上 |
| @ApiOperation("xxx接口說明") | 作用在接口方法上 |
| @ApiModel("xxxPOJO說明") | 作用在模型類上：如VO、BO |
| @ApiModelProperty(value = "xxx屬性說明",hidden = true) | 作用在類方法和屬性上，hidden設(shè)置為true可以隱藏該屬性 |
| @ApiParam("xxx參數(shù)說明") | 作用在參數(shù)、方法和字段上，類似@ApiModelProperty |
6. 使用Swagger
??完全以上幾小步配置后，再次打開swagger-ui界面就可以進(jìn)行測(cè)試了，相較于傳統(tǒng)的Postman或Curl方式測(cè)試接口，使用swagger簡(jiǎn)直就是傻瓜式操作，不需要額外說明文檔(寫得好本身就是文檔)而且更不容易出錯(cuò)，只需要錄入數(shù)據(jù)然后點(diǎn)擊Execute，如果再配合自動(dòng)化框架，可以說基本就不需要人為操作了。
End
??Swagger是個(gè)優(yōu)秀的工具，現(xiàn)在國內(nèi)已經(jīng)有很多的中小型互聯(lián)網(wǎng)公司都在使用它，相較于傳統(tǒng)的要先出Word接口文檔再測(cè)試的方式，顯然這樣也更符合現(xiàn)在的快速迭代開發(fā)行情。當(dāng)然了，提醒下大家在正式環(huán)境要記得關(guān)閉Swagger，一來出于安全考慮二來也可以節(jié)省運(yùn)存。之前看到過一篇深入Swagger原理的文章，最后分享出來給大家：API管理工具Swagger介紹及Springfox原理分析。
