【工具】Swagger2写接口注释
一、遇到的问题
作为一名coder,经常需要向别人提供接口,或者调用别人的接口。于是就有了接口参数是什么意思,要怎么传参数,返回值是什么意思……有多少调用方,就会有多少人来询问这些参数。如果是长时间之后,自己或许都不知道这些参数是什么意思。于是维护接口文档便成了一项必不可少的工作,维护文档也有很多问题:
- 如果手工写会很费劲
- 接口变更后可能会忘了同步文档
- ……
二、Swagger配置
Swagger(官方文档)可以快速帮助实现接口api的维护与简单测试。
a、引入maven依赖包
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.5.0</version> </dependency>
b、配置Swagger
@Configuration @EnableSwagger2
@Profile("dev") public class SwaggerConfig { public static final String SWAGGER_SCAN_BASE_PACKAGE = "api.doc.demo.controller"; public static final String VERSION = "1.0.0"; @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() /**api接口包扫描路径*/ .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)) /**可以根据url路径设置哪些请求加入文档,忽略哪些请求*/ .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() /**设置文档的标题*/ .title("Swagger2 接口文档示例") /**设置文档的描述*/ .description("更多内容请关注:http://www.abc.com") /**设置文档的联系方式*/ .contact(new Contact("create by XXX", "http://www.abc.com", "xxxx.@xxx.com")) /**设置文档的License信息->1.3 License information*/ .termsOfServiceUrl("www.abc.com") .license("xxx") .licenseUrl("http://www.xxx.com") /**设置文档的版本信息-> 1.1 Version information*/ .version(VERSION) .build(); } }
c、常用注解
- @ApiOperation : api说明
@ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json") @RequestMapping(value="/getList", method= RequestMethod.GET) public List<UserModel> getUserList() { return getDemoList(); }
- @ApiResponses :默认Response的基础上增加新的Response说明
- @ApiImplicitParam : 描述接口参数
@ApiImplicitParam(name = "userId",value = "用户ID",dataType = "int",paramType = "path")
- @ApiImplicitParams : 多个参数
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"),
@ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")
})
- @ApiModel : model属性
@ApiModel(value = "user", description = "user对象")
public class UserModel {
@ApiModelProperty(value = "ID", dataType = "Integer", required = true)
private Integer userId;
@ApiModelProperty(value = "用戶名", dataType = "String")
private String userName;
@ApiModelProperty(value = "性別", dataType = "Integer", allowableValues = "0,1,2")
private Integer sex;
}
这样就可以通过访问 http://localhost:8080/swagger-ui.html 看到接口API调用说明。demo