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 代码直接运行，点击http://0.0.0.0:5000/swagger就可以直接看到接口文档了。

以上！

github restplus 点击这里！
Flask-RESTPlus 文档点击这里！