Swagger - 《web开发》

Swagger Annotation 详解

是什么：流行的API管理工具。目前Swagger已经形成一个生态圈，能够管理API的整个生命周期，从设计、文档到测试与部署。
特点：
- 代码侵入式注解
- 遵循YAML文档格式
- 非常适合三端（PC、IOS及Android）的API管理，尤其适合前后端完全分离的架构模式。
- 减少没有必要的文档，符合敏捷开发理念
- 功能强大
Swagger拥有众多不同语言和平台的开源实现与工具，主要有：
- Swagger UI，基于Swagger-compliant API的一套可以展示优美文档的Web应用，在大多数情形下，都使用Swagger UI实现对API的管理与展现。
- Swagger Editor，一款以YAML格式编辑与管理API的工具，同时支持JSON格式的文档描述。
- Swagger-Core，Swagger的Java/Scala实现，并已集成 JAX-RS (Jersey, Resteasy, CXF…)、Servlets与Play Framework，即：管理Java 应用API。
- Swagger-JS，Swagger的Javascript版本实现，即：管理前端JS API。
与Java与Spring Boot后台开发语言和框架的集成：
- 开源插件springfox同时实现了Swagger UI及Swagger-Core。
- 相关注解分析：
  - 主要分为两类，一类是对Model（entity）的注解；另一类是对API（controller）的注解。
  - API的注解：针对每个Controller里包含若干个REST API
    - @Api：该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。
      - tags：API分组标签，具有相同标签的API将会被归并在一组内展示。
      - value：如果tags没有定义，value将作为Api的tags使用。
      - description：API的详细描述。
    - @ApiOperation：在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。
      - value：对操作的简单说明。
      - notes：对操作的详细说明。
      - httpMethod：HTTP请求的动作名。
        
        可选有：”GET”、”HEAD”、”POST”、”PUT”、”DELETE”、”OPTIONS”、”PATCH”。
      - code：默认为200
    - @ApiImplicitParams：注解ApiImplicitParam的容器类，以数组方式存储。
    - @ApiImplicitParam：以统一的方式对API的单一参数进行注解。
    - @ApiParam：增加对参数的元信息说明。
  - Model的注解：对于Model的注解，Swagger提供了两个：@ApiModel及@ApiModelProperty，分别用以描述Model及Model内的属性和方法。
    - @ApiModel：提供对Swagger model额外信息的描述。
      - value：model的别名，默认为类名
      - description：model的详细描述
    - @ApiModelProperty：对model属性的注解，主要的属性值有：
      - value：属性简短描述
      - example：属性的示例值
      - required：是否为必须值