参考资料
导语
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。
Swagger介绍
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
Springfox Swagger介绍
Spring 基于swagger规范,可以将基于SpringMVC和Spring Boot项目的项目代码,自动生成JSON格式的描述文件。
pom文件中导入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.0</version>
</dependency>
Swagger配置类
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any()).build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("助记宝项目接口文档")
.description("助记宝项目接口测试,所有的主键都不需要传(牵扯到ID的字段),创建时间也不传")
.version("1.0.0")
.build();
}
}
springmvc.xml设置
#开放拦截器
<mvc:interceptors>
<mvc:interceptor>
<mvc:exclude-mapping path="/swagger*/**"></mvc:exclude-mapping>
</mvc:interceptor>
</mvc:interceptors>
#开放资源
<mvc:resources mapping="/swagger-ui.html location="classpath:/META-INF/resources/" />
Swagger使用的注解
@Api注解用于类,表示标识这个类是swagger的资源 。tags表示说明 ,可以标识为类名。
@ApiOperation注解用于方法说明。value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法,默认为false。
@ApiParam注解用于方法参数,对方法参数进行了说明。
@ApiIgnore注解用于类、参数、方法上,注解后将不在Swagger UI中显示。
@ApiImplicitParam注解用于对参数说明。
@ApiImplicitParams() 注解用于方法,包含多个 @ApiImplicitParam。
@ApiResponse注解用于响应配置。
@ApiModel注解用于描述一个Model的信息。