使用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）- 服務當前無法處理請求