使用swagger做爲restful api的doc文檔生成——從源碼中去提取restful URL接口描述文檔

初衷

記得之前寫接口，寫完後會整理一份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