不同于fastapi flask等老框架没有集成swagger需要第三方辅助, 现在列出两个常用的辅助库
提醒自己
系统学习,少看别人博客直接入手官方文档可以少走弯路
系统学习,少看别人博客直接入手官方文档可以少走弯路
系统学习,少看别人博客直接入手官方文档可以少走弯路
flasgger
- 官方文档
- 完整示例
1. 其中 template 部分可以提配成 json或者 yaml 通过 Swagger 函数的 template_file 参数进行传参;from flask import Flask, jsonify from flasgger import Swagger app = Flask(__name__) template = { "swagger": "2.0", "info": { "title": "My API", "description": "API for my data", "contact": { "responsibleOrganization": "ME", "responsibleDeveloper": "Me", "email": "me@me.com", "url": "www.me.com", }, "termsOfService": "http://me.com/terms", "version": "V2" }, "host": "127.0.0.1:8686", # overrides localhost:500 "basePath": "/", # base bash for blueprint registration "schemes": [ "http", "https" ], "operationId": "getmyData", "paths": { "/colors/{palette}/": { "get": { "tags": [ "colors" ], "summary": "Add a new pet to the store", "description": "api test", "operationId": "addPet", "consumes": [ "application/json", "application/xml" ], "parameters": [ { "name": "palette", "in": "path", "type": "string", "description": "palette all/cmyk/rgb", "required": True, }, { "name": "tag", "in": "query", "type": "string", "description": "palette all/cmyk/rgb", "required": True, } ], "responses": { "405": { "description": "Invalid input" } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] }}} } swagger = Swagger(app, template=template) @app.route('/colors/<string:palette>/') def colors(palette): all_colors = { 'cmyk': ['cyan', 'magenta', 'yellow', 'black'], 'rgb': ['red', 'green', 'blue'] } print "palette:", palette if palette == 'all': result = all_colors else: result = {palette: all_colors.get(palette)} return jsonify(result) app.run(debug=True)
2. 详细的配置在 Swagger 官网中非常详细; Swagger官网
3. 我建议这样配置还有其他方式的配置, 请移步 本节开头的官网 - 运行后访问: http://127.0.0.1:5000/apidocs
- 截图
flask-restplus
- 官方文档
- 完整示例
from flask import Flask from flask_restplus import Api, Resource, fields from werkzeug.contrib.fixers import ProxyFix app = Flask(__name__) app.wsgi_app = ProxyFix(app.wsgi_app) api = Api(app, version='1.0', title='TodoMVC API', description='A simple TodoMVC API', ) ns = api.namespace('todosssss', description='TODO operations') todo = api.model('Todo', { 'id': fields.Integer(readonly=True, description='The task unique identifier'), 'task': fields.String(required=True, description='The task details') }) class TodoDAO(object): def __init__(self): self.counter = 0 self.todos = [] def get(self, id): for todo in self.todos: if todo['id'] == id: return todo api.abort(404, "Todo {} doesn't exist".format(id)) def create(self, data): todo = data todo['id'] = self.counter = self.counter + 1 self.todos.append(todo) return todo def update(self, id, data): todo = self.get(id) todo.update(data) return todo def delete(self, id): todo = self.get(id) self.todos.remove(todo) DAO = TodoDAO() DAO.create({'task': 'Build an API'}) DAO.create({'task': '?????'}) DAO.create({'task': 'profit!'}) @ns.route('/') class TodoList(Resource): '''Shows a list of all todos, and lets you POST to add new tasks''' @ns.doc('list_todos') @ns.marshal_list_with(todo) def get(self): '''List all tasks''' return DAO.todos @ns.doc('create_todo') @ns.expect(todo) @ns.marshal_with(todo, code=201) def post(self): '''Create a new task''' return DAO.create(api.payload), 201 @ns.route('/<int:id>') @ns.response(404, 'Todo not found') @ns.param('id', 'The task identifier') class Todo(Resource): '''Show a single todo item and lets you delete them''' @ns.doc('get_todo') @ns.marshal_with(todo) def get(self, id): '''Fetch a given resource''' return DAO.get(id) @ns.doc('delete_todo') @ns.response(204, 'Todo deleted') def delete(self, id): '''Delete a task given its identifier''' DAO.delete(id) return '', 204 @ns.expect(todo) @ns.marshal_with(todo) def put(self, id): '''Update a task given its identifier''' return DAO.update(id, api.payload) if __name__ == '__main__': app.run(debug=True)
- 运行后访问: http://127.0.0.1:5000/
- 截图
Swagger如何编写配置文件
- 可以去官方提供的Editor里去边看官方文档边改出自己项目的配置,地址如下
- Swagger Editor
- 截图