Flask 自动生成 Swagger/OpenAPI 3.0

在本文中，我们将介绍如何使用 Flask 和 Python 来自动生成 Swagger/OpenAPI 3.0 文档。

阅读更多：Flask 教程

什么是Swagger/OpenAPI？

Swagger 是一种用于描述 RESTful 服务的 API 规范，它提供了一种自动生成文档和生成客户端代码的方式。OpenAPI 是 Swagger 的下一代规范，用于定义 RESTful API 的格式和规则。

Flask-Swagger

Flask-Swagger 是一个用于集成 Swagger 和 Flask 的插件。它可以自动根据 Flask 应用程序中的路由信息生成 Swagger/OpenAPI 3.0 文档。

首先，我们需要安装 Flask-Swagger。可以使用 pip 命令来安装：

pip install flask-swagger

安装完成后，在 Flask 应用程序中导入 Flask-Swagger：

from flask_swagger import Swagger

接下来，创建一个 Flask 应用程序实例，并初始化 Swagger：

app = Flask(__name__)
swagger = Swagger(app)

现在，我们可以使用 @app.route 装饰器定义 API 路由，并添加 Swagger 注释。下面是一个简单的示例：

@app.route('/users', methods=['GET'])
# Swagger 注释
# @swagger
def get_users():
    """
    获取用户列表

    This is a sample request.

    ---
    responses:
      200:
        description: 成功获取用户列表
    """

    # 实现获取用户列表的逻辑
    pass

在该示例代码中，@app.route 装饰器用于定义路由和请求方法。@swagger 注释用于告诉 Flask-Swagger 该路由需要生成 Swagger 文档。

然后，我们可以使用 Swagger UI 来查看生成的文档。通过浏览器访问 /apidocs 路径即可打开 Swagger UI。

Flask-RESTPlus

Flask-RESTPlus 是一个基于 Flask 和 Flask-Swagger 的插件，它提供了更加方便和简洁的方式来生成 Swagger 文档。

首先，安装 Flask-RESTPlus：

pip install flask-restplus

导入 Flask-RESTPlus：

from flask_restplus import Api, Resource

创建 Flask 应用程序实例，并初始化 Flask-RESTPlus：

app = Flask(__name__)
api = Api(app, version='1.0', title='API', description='API 文档')

然后，我们可以使用 api.route 装饰器定义 API 路由，并添加 Swagger 注释。下面是一个示例：

@api.route('/users')
class UserList(Resource):
    """
    用户列表
    """

    @api.doc(responses={200: '成功获取用户列表'})
    def get(self):
        # 实现获取用户列表的逻辑
        pass

在该示例代码中，@api.route 装饰器用于定义路由，@api.doc 注释用于添加 Swagger 文档中的详细信息。

和 Flask-Swagger 类似，我们可以使用 Swagger UI 来查看生成的文档。

总结

本文介绍了如何使用 Flask 和 Python 自动生成 Swagger/OpenAPI 3.0 文档。我们可以使用 Flask-Swagger 或 Flask-RESTPlus 插件来实现自动生成文档的功能。通过在代码中添加相应的注释，我们可以自动生成包含 API 路由、参数和响应等信息的 Swagger 文档，并使用 Swagger UI 来查看文档。

希望本文对你理解并使用 Flask 自动生成 Swagger/OpenAPI 3.0 文档有所帮助！