Swagger
Swagger号称是史上最流行的、最好用的API接口文档构建工具，它支持多种语言包括Java在内，本文仅关注如何使用Spring Boot来集成Swagger，更多关于Swagger的介绍可以查看以下几个链接。
SpringFox
SpringFox最初叫Swagger-SpringMVC，从字面意义上简单来理解是使用了SpringMVC来集成Swagger，后来演变成SpringFox这么一个项目(或组织)，SpringFox官网有这么一句：Automated JSON API documentation for API's built with Spring(针对Spring构建的API的自动化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启动类上添加@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注解得类，还可以扫描任意位置，指定包以及针对方法上的指定注解
.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. 运行效果
启动Spring Boot后，可以点击查看(更改为你的本地地址) http://localhost:8080/swagger-ui.html#/ ，效果如下：
5. 常用注解
Swagger的所有注解定义在io.swagger.annotations包下，下面列一些经常用到的，未列举出来的可以另行查阅说明：
| Swagger注解 | 简单说明 |
|---|---|
| @Api(tags = "xxx模块说明") | 作用在模块类上 |
| @ApiOperation("xxx接口说明") | 作用在接口方法上 |
| @ApiModel("xxxPOJO说明") | 作用在模型类上：如VO、BO |
| @ApiModelProperty(value = "xxx属性说明",hidden = true) | 作用在类方法和属性上，hidden设置为true可以隐藏该属性 |
| @ApiParam("xxx参数说明") | 作用在参数、方法和字段上，类似@ApiModelProperty |
6. 使用Swagger
完全以上几小步配置后，再次打开swagger-ui界面就可以进行测试了，相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。
End
Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运存。之前看到过一篇深入Swagger原理的文章，最后分享出来给大家：API管理工具Swagger介绍及Springfox原理分析。
