使用swagger编写TESTFul的API文档

---

1 前驱知识

1.1 Open API

Open API即开放API,也称开放平台。 所谓的开放API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的API，所开放的API就被称作OpenAPI（开放API）。

1.2 swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

swagger支持API文档编写以及导出前后端框架的功能。由于本次项目前后端框架已经确定，因此只使用API文档编辑以及可视化显示UI的功能。

API文档编辑器-swagger editor

使用了swagger2.0标准编辑

1.3 RESTFul

REST全称是Representational State Transfer，中文意思是表述（编者注：通常译为表征）性状态转移。 是在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

RESTFul详解

2 编写技巧

2.1 合理引用

2.1.1 一处定义，处处引用·

swagger在编写的时候具有一处定义，处处引用的特性，这在很大程度上为设计提供了很大的便利。例如：
当我们写两条API，都需要返回一个结构体。我们会这样编辑：

 /user:
    get:
===================================
      responses:
        200:
          description: A list of User
          schema:
            type: array
            items:
              required:
              - userInfo
            properties:
              name:
                type: string
              school:
                type: string
              dormitory:
                type: string
======================================
    post:
======================================
      parameters:
        - name: User
          in: body
          description: The user to create.
          schema:
            required:
              - userInfo
            properties:
              name:
                type: string
              school:
                type: string
              dormitory:
                type: string

但是如果运用一次定义，处处引用的特性，我们就可以通过一次定义，而在两次需要的地方引用，编辑更加简洁高效。

# 添加定义

definitions:
  User:
    required:
      - userInfo
          properties:
            name:
              type: string
            school:
              type: string
            dormitory:
              type: string

再在需要的地方引用。

      responses:
        200:
          description: A list of User
          schema:
            $ref: "#/definitions/Person"

2.1.2 优缺点

• 优点

优点是显而易见的，能够方便编辑，在书写的过程中，更为流畅且简洁。大篇幅的引用被替代，更加的美观。

• 缺点

一方面，本项目中很多API需要的结构都是不一样的，这就导致可能会创建大量的结构体。十分容易导致引用错误。

另一方面，为了书写、实现简便。可能会将相似的结构体合并，可能导致数据的冗余。

2.2 分辨GET POST PUT方法

2.2.1 方法区别

方法名	安全性	幂等性	功能
GET	是	是	请求指定的页面信息，并返回实体主体
PUT	否	是	从客户端向服务器传送的数据取代指定的文档的内容
POST	否	否	请求服务器接受所指定的文档作为对所标识的URI的新的从属实体

2.3 响应码

2.3.1 GET

200（OK） - 表示已在响应中发出
204（无内容） - 资源有空表示
301（Moved Permanently） - 资源的URI已被更新
303（See Other） - 其他（如，负载均衡）
304（not modified）- 资源未更改（缓存）
400 （bad request）- 指代坏请求（如，参数错误）
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务端当前无法处理请求

2.3.2 POST

200（OK）- 如果现有资源已被更改
201（created）- 如果新资源被创建
202（accepted）- 已接受处理请求但尚未完成（异步处理）
301（Moved Permanently）- 资源的URI被更新
303（See Other）- 其他（如，负载均衡）
400（bad request）- 指代坏请求
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前无法处理请求

2.3.3 PUT

200 （OK）- 如果已存在资源被更改
201 （created）- 如果新资源被创建
301（Moved Permanently）- 资源的URI已更改
303 （See Other）- 其他（如，负载均衡）
400 （bad request）- 指代坏请求
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前无法处理请求