使用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