秒懂API文档工具swagger的使用
swagger是一个接口文档的生成框架
为什么要使用swagger？
区别去传统文档的两个优点：1.生成在线文档动态更新 （文档根据当前的接口生成） 避免了文档版本多，代码文档不同步等问题
2.在线restful形式的接口 边看文档的同时测试接口，取代了了传统的postman、curl等，那是相当的方便
如何使用？ 这里用spring boot的restful开发做讲解，IDE使用intelli idea
第一步 添加maven依赖
在你的api项目的pom.xml 中添加两个依赖
springfox-swagger2 和springfox-swagger-ui 下载到maven的中央仓库 http://mvnrepository.com/
第二步 创建swagger2配置类
如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
第三步 开启swagger2 启动类加注解@Enableswagger2
第四步 给函数添加注解
在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。
这样swagger2与springboot就集成完毕了。
看下最终效果吧：
浏览改地址，访问主页面：http://localhost:8080/swagger-ui.html#
浏览改地址，访问swagger专有jsonAPI： http://localhost:8080/v2/api-docs
输入id后，我们可以看到查询结果：、
是不是很方便，我们不用像postman一样来编写入口，swagger2自动完成：
而且实时更新：
全部注释列表
@Api
Api 标记可以标记一个Controller类做为swagger 文档资源，使用方式
| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | For example, “application/json, application/xml” |
| consumes | For example, “application/json, application/xml” |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true 将在文档中隐藏 |
@ApiOperation每一个url资源的定义,使用方式
| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | For example, “application/json, application/xml” |
| consumes | For example, “application/json, application/xml” |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true 将在文档中隐藏 |
| response | 返回的对象 |
| responseContainer | 这些对象是有效的 “List”, “Set” or “Map”.，其他无效 |
| httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
| code | http的状态码 默认 200 |
| extensions | 扩展属性 |
@ApiParam标记
public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)
| 属性名称 | 备注 |
|---|---|
| name | 属性名称 |
| value | 属性值 |
| defaultValue | 默认属性值 |
| allowableValues | 可以不配置 |
| required | 是否属性必填 |
| access | 不过多描述 |
| allowMultiple | 默认为false |
| hidden | 隐藏该属性 |
| example | 举例子 |
@ApiImplicitParam对容器的描述
| 属性名称 | 备注 |
|---|---|
| name | 属性名称 |
| value | 属性值 |
| defaultValue | 默认值 |
| allowableValues | 可以不可配置 |
| required | 是否属性必填 |
| access | 不可过多描述 |
| allowMutiple | 默认为false |
| dataType | 数据类型 |
| paramType | 参数类型 |
@ApiResponse
| 属性名称 | 备注 |
|---|---|
| code | http的状态码 |
| message | 描述 |
| response | 默认响应类 Void |
| reference | 参考ApiOperation中配置 |
| responseHeaders | 参考 ResponseHeader 属性配置说明 |
| responseContainer | 参考ApiOperation中配置 |
@ResponseHeader(name=”head1”,description=”response head conf”)
| 属性名称 | 备注 |
|---|---|
| name | 响应头名称 |
| description | 头描述 |
| response | 默认响应类 Void |
| responseContainer | 参考ApiOperation中配置 |
4文档编写规范建议
- entity的描述
@ApiModel(description = “我是描述”,value = “用户”)
对实体的描述
description：在v2/api-docs的实体看到描述，
value的值在@ApiImplicitParam注解中的dataType可用，
@ApiModelProperty(value = “用户姓名”,required = true,dataType = “String”)
private String name;
对字段的描述
value：1，入参和出参的ModelModel Schema选项卡可见，2，在v2/api-docs的实体字段描述可见
required：该属性是否必填写
dataType:该字段的数据类型
- controller的描述
@Api(value = “API”, description = “用户接口详情”,tags=”A”)
对controler的描述
value:访问某个controller的url的根路径值
description：对于该controller的的大概描述
tags:把api接口进行分分组
@ApiOperation(value = “获取用户详细信息”, notes = “根据url的id来获取用户详细信息”,httpMethod =”GET”)
对该方法的描述
value:主页面中对该接口的描述，位置在接口的最右边
notes：点开接口后，第一段描述。
httpMethod:HTTP请求的动作名，可选值有：”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “String”, paramType = “path”)
对参数的描述，如果多个参数需要用@ApiImplicitParams对其进行包裹
name:参数名称
value：参数的简短描述
required:是否必须传递的参数
dataType:参数类型，可以为类名，也可以为基本类型（String，int，Boolean）
paramType：参数的传入（请求）类型，可选的值有path, query, body, header or form。（如果在路径中提取参数用path比如:在／A／{XXX}路径中得到XXX的值）
@ApiParam(name = “user”, value = “userValue”, required = true)
对参数元信息的说明，一般这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下，和ApiImplicitParam注解类似
required:该参数是否必填
value:该参数的简短介绍
@ApiResponse(code = 200, message = “Successful — 请求已完成”)
返回状态码的描述,如果有多个可以使用@ApiResponses注解进行包裹
code:服务器返回的状态码
message：服务器返回状态码的简短说明
github地址：https://github.com/chinafire/swagger-example.git
swagger官方文档： https://swagger.io/docs/