使用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的功能。
使用了swagger2.0标准编辑
1.3 RESTFul
REST全称是Representational State Transfer，中文意思是表述（编者注：通常译为表征）性状态转移。 是在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。如果一个架构符合REST的约束条件和原则，我们就称它为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）- 服务当前无法处理请求