一、 FlaskSwagger初探
FlaskSwagger是用于Flask应用程序的一个工具,可自动生成和展示API文档,以便更轻松地管理API。
使用FlaskSwagger,我们不仅可以直观地查看API的接口文档,也可以在SwaggerUI提供的交互性界面中对API进行测试和调试。
from flask import Flask
from flask_restful import Api, Resource
from flask_swagger import swagger
app = Flask(__name__)
api = Api(app)
class HelloWorld(Resource):
def get(self):
return {'hello': 'world'}
api.add_resource(HelloWorld, '/')
@app.route('/spec')
def spec():
return swagger(app)
二、 部署FlaskSwagger
下面是部署FlaskSwagger的具体步骤:
1. 安装FlaskSwagger
pip install flask-swagger
2. 在Flask应用中引用FlaskSwagger。
from flask_swagger import swagger
3. 设置Flask应用的文档URL
@app.route('/spec')
def spec():
return swagger(app)
4. 运行Flask应用
if __name__ == '__main__':
app.run(debug=True)
三、 在SwaggerUI中展示API文档
SwaggerUI是一种专门设计用于API文档的交互式界面,可以更加清晰、明了的展示出API的各个字段、参数,方便用户与API进行交互式地体验和调试。
通过FlaskSwagger,我们可以很容易地实现将SwaggerUI和API文档整合在一起
只需在Flask代码中添加以下路由即可:
from flask import Flask, request
from flask_restful import Resource, Api
from flask_swagger import swagger
from flask_swagger_ui import get_swaggerui_blueprint
app = Flask(__name__)
api = Api(app)
SWAGGER_URL = '/api/docs' # URL for exposing Swagger UI (without trailing '/')
API_URL = '/spec' # Our API url (can of course be a local resource)
# Call factory function to create our blueprint
swaggerui_blueprint = get_swaggerui_blueprint(
SWAGGER_URL,
API_URL,
config={
'app_name': "My Test Application"
},
)
# Register blueprint at URL
# (URL must match the one given to factory function above)
app.register_blueprint(swaggerui_blueprint, url_prefix=SWAGGER_URL)
class HelloWorld(Resource):
def get(self):
return {'hello': 'world'}
api.add_resource(HelloWorld, '/')
@app.route('/spec')
def spec():
return swagger(app)
if __name__ == '__main__':
app.run(debug=True)
四、 API文档的自定义
在FlaskSwagger自动生成的API文档中,我们可以通过下面两种方式进行自定义:
1. 使用Python装饰器自定义API信息
我们可以使用下述装饰器来自定义API的信息:
from flask import Flask
from flask_restful import Resource, Api, fields, marshal_with
from flask_swagger import swagger
app = Flask(__name__)
api = Api(app)
resource_fields = {
'name': fields.String,
'address': fields.String,
'date_updated': fields.DateTime,
}
class HelloWorld(Resource):
@marshal_with(resource_fields)
def get(self):
"""
This endpoint will return a list of all the existing smells
---
tags:
- Smelly Things
definitions:
- schema:
id: response
properties:
name:
type: string
default: "John"
address:
type: string
default: "Street 1"
date_updated:
type: string
format: date-time
default: "2016-01-01T10:00:00Z"
- schema:
id: error_model
properties:
error:
type: string
description: description of error (should be short)
responses:
200:
description: A list of all the smells
schema:
$ref: '#/definitions/response'
500:
description: An error occurred
schema:
$ref: '#/definitions/error_model'
"""
return {'name': 'John', 'address': 'street 1', 'date_updated': '2016-01-01'}
api.add_resource(HelloWorld, '/')
@app.route('/spec')
def spec():
swag = swagger(app)
swag['info']['title'] = 'My API'
swag['info']['description'] = 'Customize Swagger within Flask'
return swag
2. 在SwaggerUI页面中手动编辑API文档
在SwaggerUI的界面中,我们可以编辑API文档的信息,包括操作和参数等信息,可以方便快捷地对API进行调试和测试。
五、 总结
FlaskSwagger是一个非常实用的工具,能够更加方便地管理API文档,让整个开发的过程更加轻松愉快。