初衷

記得以前寫接口，寫完后會整理一份API接口文檔，而文檔的格式如果沒有具體要求的話，最終展示的文檔則完全決定於開發者的心情。也許多點，也許少點。甚至，接口總是需要適應新需求的，修改了，增加了，這份文檔維護起來就很困難了。於是發現了swagger，自動生成文檔的工具。

swagger介紹

首先，官網這樣寫的：

Swagger – The World's Most Popular Framework for APIs.

因為自強所以自信。swagger官方更新很給力，各種版本的更新都有。swagger會掃描配置的API文檔格式自動生成一份json數據，而swagger官方也提供了ui來做通常的展示，當然也支持自定義ui的。不過對后端開發者來說，能用就可以了，官方就可以了。

最強的是，不僅展示API，而且可以調用訪問，只要輸入參數既可以try it out.

效果為先，最終展示doc界面，也可以設置為中文：

針對python flask的swagger客戶端：

flask-swagger

A Swagger 2.0 spec extractor for Flask

Install:

pip install flask-swagger

Flask-swagger provides a method (swagger) that inspects the Flask app for endpoints that contain YAML docstrings with Swagger 2.0 Operation objects.

class UserAPI(MethodView): def post(self): """  Create a new user  ---  tags:  - users  definitions:  - schema:  id: Group  properties:  name:  type: string  description: the group's name  parameters:  - in: body  name: body  schema:  id: User  required:  - email  - name  properties:  email:  type: string  description: email for user  name:  type: string  description: name for user  address:  description: address for user  schema:  id: Address  properties:  street:  type: string  state:  type: string  country:  type: string  postalcode:  type: string  groups:  type: array  description: list of groups  items:  $ref: "#/definitions/Group"  responses:  201:  description: User created  """ return {}

可以參考：https://github.com/gangverk/flask-swagger

針對Java spring mvc的可以看這里：http://www.cnblogs.com/woshimrf/p/5863318.html

針對swagger yaml本身的一些介紹：https://www.gitbook.com/book/huangwenchao/swagger/details