初衷
记得以前写接口，写完后会整理一份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