swagger 框架

swagger 框架

---

简介

Swagger 是一款目前世界最流行的 API 管理工具。目前Swagger 已经形成一个生态圈，能够管理API 的整个生命周期，从设计、文档到测试与部署。 Swagger 的几个重要特性：

• 代码侵入式注解
• 遵循YAML 文档格式
• 非常适合三端（PC、IOS、以及Android） 的 API 管理，尤其适合前后端完全分离的架构模式
• 减少没有必要的文档，符合敏捷开发理念
• 功能强大

作用：

• 接口的文档在线自动生成
• 功能测试

优点：

1. 大大减少前后端的沟通
2. 方便查找和测试接口
3. 提高团队的开发效率
4. 方便新人了解项目

---

一、常用注解

swagger 通过在 controller 中，声明注解对 API 文档进行说明

1. @Api()
   用在请求的类上，表示对类的说明，也代表了这个类是swagger2 的资源
   参数：
   1 .tags: 说明该类的作用，参数是个数组，可以填多个。
   2 .value=“该参数没什么意义，在UI界面上不显示，所以不用配置”
   3 .description = “用户基本信息操作”

2. @ApiOperation():
   用于方法，表示一个http 请求访问该方法的操作
   参数：
   1 . value=“方法的用途和作用”
   2 .notes=“方法的注意事项和备注”
   3 .tags ：说明该方法的作用，参数是个数组，可以是多个
   4 .格式： tags={“作用1”,“作用2”}
   5 . {在这里不建议使用这个参数，会使界面看上去很乱，前两个常用}

3. @ApiModel()：
   用于响应实体类上，用于说明实体作用
   参数：
   description=“描述实体的作用”

4. @ApiModelProperty:
   用在属性上，描述实体类的属性
   参数：
   1 .value=“用户名” 描述参数的意义
   2 .name=“name” 参数的变量名
   3 .required=true 参数是否必选

5. @ApiImplictParams:
   用在请求的方法上，包含多@ApliImplictParam

6. @ApliImplictParam ：
   用于方法，表示单独的请求参数
   参数：
   1 . name=“参数ming”
   2 . value=“参数说明”
   3 . dataType=“数据类型”
   4 . paramType=“query” 表示参数放在哪里
   5 . header 请求参数的获取：@RequestHeader
   6 · query 请求参数的获取：@RequestParam
   7 · path（用于restful接口） 请求参数的获取：@PathVariable
   8 · body（不常用）
   9 · form（不常用）
   10 . defaultValue=“参数的默认值”
   11 . required=“true” 表示参数是否必须传

7. @ApiParam()：
   用于方法，参数，字段说明 表示对参数的要求和说明
   参数：
   name=“参数名称”
   value=“参数的简要说明”
   defaultValue=“参数默认值”
   required=“true” 表示属性是否必填，默认为false

8. @ApiResponses：
   用于请求的方法上，根据响应码表示不同响应
   一个@ApiResponses包含多个@ApiResponse

9. @ApiResponse：
   用在请求的方法上，表示不同的响应
   参数：
   code=“404” 表示响应码(int型)，可自定义
   message=“状态码对应的响应信息”

10. @ApiIgnore()：
    用于类或者方法上，不被显示在页面上