Flasgger 简介
Flasgger 是一个 Flask 扩展，它从 API 中注册的所有 Flask 视图生成一个 OpenAPI 规范。Flasgger 带有一个内置的 SwaggerUI，允许可视化和交互 API 资源。Flasgger 易于使用，并与 Flask 框架集成。
Flasgger 的优点包括：
- 从 Flask 视图自动生成 OpenAPI 规范，避免手动编写繁琐的文档。
- 内置的 SwaggerUI 界面可以可视化和交互 API 资源，方便调试和测试。
- 可以使用 YAML、Python 字典或 Marshmallow Schemas 定义模式，并提供数据验证功能。
- 支持简单的函数视图或使用 @swag_from 装饰器和 SwaggerView 等高级用法。
- 与 Flask-RESTful 兼容，支持使用资源和 swag 规范。
- 支持使用 Marshmallow APISpec 作为规范的基本模板，提供更多灵活性和扩展性。
Flasgger 使用教程
安装 flasgger
安装前确保你已经安装了setuptools。
pip install -U setuptools
pip install flasgger
编写 route 注释
from flask import Flask, jsonifyfrom flasgger import Swaggerapp = Flask(__name__)
swagger = Swagger(app)
@app.route('/colors/<palette>/')def colors(palette):
"""Example endpoint returning a list of colors by palette This is using docstrings for specifications. --- parameters: - name: palette in: path type: string enum: ['all', 'rgb', 'cmyk'] required: true default: all definitions: Palette: type: object properties: palette_name: type: array items: $ref: '#/definitions/Color' Color: type: string responses: 200: description: A list of colors (may be filtered by palette) schema: $ref: '#/definitions/Palette' examples: rgb: ['red', 'green', 'blue'] """all_colors = {
'cmyk': ['cyan', 'magenta', 'yellow', 'black'],
'rgb': ['red', 'green', 'blue']
}
if palette == 'all':
result = all_colorselse:
result = {palette: all_colors.get(palette)}
return jsonify(result)
app.run(debug=True)
浏览器打开 Url
这样我们就获得了一个 Swagger UI。
http://localhost:5000/apidocs
更好用的 API 文档工具
编写代码下来我们会发现生成 API 文档非常简单，除了生成 API 文档后，怎么测试 API ？怎么在线分享 API 文档？ 我这里强烈建议使用 Apifox ， 相对使用 Flask 插件， 直接使用 Apifox 这个 API 设计， 调试，协作和 Mock 一体化工具 更方便，API 设计、调试、测试、文档分享能力也更加完善 。
- 可视化编辑器：Apifox 提供了一个可视化的编辑器，可以让我们轻松地在 Web 界面上创建和修改 API 文档。Flasgger 需要在代码中使用装饰器和 YAML 文件来定义规范，可能需要更多的技术知识和时间。
- 团队协作：Apifox 可以帮助整个团队协作创建和维护 API 文档，可以在同一文档中同时进行编辑和注释。Flasgger 需要在代码库中维护 YAML 文件，并且可能需要一些额外的工具来确保团队成员之间的同步。
- 自动化生成：Apifox 可以将 API 文档导出为 OpenAPI 规范、SwaggerUI 界面和其他格式，可以轻松地与其他开发工具和流程集成。Flasgger 需要在代码库中运行和维护 Flask 应用程序，并确保所有视图都正确地定义和记录规范。
快来体验开箱即用的 API 工具吧，完全免费！