flask自动生成swagger的api接口文档
生成接口文档一直是一件麻烦的事，这里想自动化生成swagger的接口文档，所以用了一个框架：
Flask-RESTPlus链接里有安装教程。
结合yaml版本会更容易理解： yaml版本传送门
本文依旧是以代码+效果图的方式表现：
from flask_restplus import Api, Resource, fields
app = Flask(__name__)
api = Api(app, version='1.0', title='AUTH API', description='A authenticate user and save cloud accounts API')
au = api.namespace('auth', path='/')
ca = api.namespace('cloud accounts', path='/')
acs = api.namespace('accounts', path='/')
bca = api.namespace('binding cloud accounts', path='/')
导包 Api， Resource， fields
api：以Api创建一个实例。version，title，description ：关于该api的版本，标题和描述
api.namespace ：是命名空间，很多接口都有get，post，命名空间把他们分隔开，可理解为蓝图。
path：代表他们的路由地址，这里让他们都使用route的地址，不写的话会把命名空间的name加到路由地址的最前面
接下来是model：
parser = api.parser()
parser.add_argument('accessToken', location='headers')
auth = api.model('Auth', {
'usernameOrEmail': fields.String(required=True),
'password': fields.String(required=True)
})
token = api.model('AccessToken', {
'accessToken': fields.String(required=True)
})
parser : 添加参数项，此处是要在请求区域内添加header参数，与@acs.expect(parser) 联用
model：请求内容，或者是响应内容，都可以用model描述，请求内容与@acs.doc(body=model)联用，响应内容与@acs.marshal_with(token) 联用
区别：装饰器装饰的地方不同，注意下方栗子。
接下来看路由：
@acs.route('/accounts')
@acs.expect(parser)
@acs.response(400, 'params error')
class CreateAccounts(Resource):
@acs.doc('A description of what this function does')
@acs.doc(body=acc_obj)
@acs.marshal_with(token)
def post(self):
...
return {'accessToken': b}
这里的命名空间是acs，所以所有的装饰器都是使用acs这个实例。
route：是路由地址
@acs.expect(parser) : 这里就是添加请求头参数了， 装饰在class上面就是所有的方法都需要这个参数
response：相应内容，装饰在class上面就是所有的方法都回有这个相应
class CreateAccounts(Resource)： 这里就不能直接使用方法了，需要创建一个继承Resource的类，在类里写入请求方法。
@acs.doc： 描述你的这个方法的作用
@acs.doc(body=acc_obj) ： 把acc_obj这个model放入请求的body中，它是可以做validate的，只要在model后面加上validate=True。
@acs.marshal_with(token)：把token这个model放入相应体中，也是可以做validate的，如果响应体写了，那么最后return的时候必须以键值对的形式return该model的参数名。
这个图中的model没写，可参考上图的model。
当api需要请求参数时：
@ca.route('/accounts/<string:usernameOrEmail>/cloudAccounts/<string:account_name>')
@ca.expect(parser)
@ca.response(400, 'params error')
@ca.doc(params={'usernameOrEmail': 'An account'})
@ca.doc(params={'account_name': 'an unique account_name of cloud account'})
class CloudAccountURD(Resource):
@ca.doc('Finds a cloud accounts by clound_account_name')
def get(self, usernameOrEmail, account_name):
pass
@ca.doc: 描述参数和参数的作用
在底下的方法内可以直接获取参数
那么大致的装饰器作用都已经介绍了，下面把部分项目代码和文档效果图都发出来：
代码中的@token_validate是我自己写的用来验证token的，不是框架里面的。
flask 代码直接运行，点击running的链接就可以直接看到接口文档了。
以上！