Flask 插件 - 集成 Swagger

简介

Flask-RESTX 提供了与 Swagger UI 的无缝集成，使得开发者能够轻松地为 API 提供交互式文档，方便 API 测试和使用。Swagger UI 是一个开源工具，可以动态显示 API 文档，并允许用户在页面上直接进行 API 调用。

在 Flask-RESTX 中，Swagger UI 是自动生成的，只需要配置简单的参数和路由，API 文档便会自动呈现。

uml diagram

安装 Flask-RESTX

如果还没有安装 Flask-RESTX，可以通过 pip 来安装。

pip install flask-restx

使用 Flask-RESTX 接口管理

创建 Flask 应用并集成 Flask-RESTX
查看 Swagger UI 文档
定义数据模型
添加 Swagger 文档描述

创建 Flask 应用并集成 Flask-RESTX

Flask-RESTX 会自动生成 Swagger 文档，所以需要创建一个简单的 Flask 应用，并通过 Api 对象注册资源。

from flask import Flask
from flask_restx import Api, Resource

# 创建 Flask 应用实例
app = Flask(__name__)

# 创建 Api 实例，这个实例用于集成 Flask-RESTX
api = Api(
    app,
    version='1.0',
    title='学生管理系统 API',
    description='学生管理系统 API，管理学生信息',
    doc='/docs' # Swagger UI 文档页面的路径
)


# 创建一个资源
class HelloWorld(Resource):

    # 指定请求方法为 get
    def get(self):
        return {'message': 'Hello, World'}


# 注册资源与路由
api.add_resource(HelloWorld, '/')

if __name__ == '__main__':
    app.run(debug=True)

Api(app, ...)：创建 Flask-RESTX 的 API 实例，自动集成 Swagger 文档。
version='1.0'：API 版本。
title='学生管理系统 API'：API 标题。
description='学生管理系统 API'：API 描述。
doc='/docs'：Swagger UI 文档的路径，默认情况下，Flask-RESTX 会将文档地址放置在 /swagger 或 /docs 上。
api.add_resource(HelloWorld, '/')：将 HelloWorld 资源与 / 路由绑定。

查看 Swagger UI 文档

运行 Flask 应用后，访问 URL http://127.0.0.1:5000/docs，可以看到自动生成的 Swagger UI 文档页面。

在这个页面，你可以查看 API 的所有资源、方法（如 GET、POST 等），并直接通过 Swagger UI 调用 API 接口。

定义数据模型

Flask-RESTX 提供了 api.model 来定义请求和响应的数据模型。数据模型可以让我们更好地控制接口的输入和输出，同时让 Swagger 自动生成相应的文档。

from flask import Flask
from flask_restx import Api, Resource, fields

# 创建 Flask 应用实例
app = Flask(__name__)

# 创建 Api 实例，这个实例用于集成 Flask-RESTX
api = Api(
    app,
    version='1.0',
    title='学生管理系统 API',
    description='学生管理系统 API，管理学生信息',
    doc='/docs' # Swagger UI 文档页面的路径
)

# 定义数据模型
student_model = api.model('Student', {
    'id': fields.Integer(required=True, description='The student ID'),
    'name': fields.String(required=True, description='The student name'),
    'age': fields.Integer(required=True, description='The student age'),
    'class': fields.String(required=True, description='The student class'),
})

使用 api.model 来定义学生数据模型。
定义数据的类型：
- fields.Integer：整型
- fields.String：字符串类型
定义是否必填：required=True
定义描述信息：description

定义接口路由

from flask import Flask
from flask_restx import Api, Resource, fields

# 创建 Flask 应用实例
app = Flask(__name__)

# 创建 Api 实例，这个实例用于集成 Flask-RESTX
api = Api(
    app,
    version='1.0',
    title='学生管理系统 API',
    description='学生管理系统 API，管理学生信息',
    doc='/docs' # Swagger UI 文档页面的路径
)

# 定义数据模型
student_model = api.model('Student', {
    # fields.Integer 代表整型，required=True 代表必填，description 描述信息
    'id': fields.Integer(required=True, description='The student ID'),
    # fields.String 代表字符串类型
    'name': fields.String(required=True, description='The student name'),
    'age': fields.Integer(required=True, description='The student age'),
    'class': fields.String(required=True, description='The student class'),
})


# 创建资源
class Student(Resource):

    # 添加 Swagger 文档中的响应状态码和描述
    @api.doc(responses={200: 'Success', 404: 'Not Found'})
    # 指定返回数据时应用模型
    @api.marshal_with(student_model)
    # 指定请求方法为 get
    def get(self, student_id):
        # 模拟获取学生数据
        student_data = {
            'id': student_id,
            'name': 'John Doe',
            'age': 20,
            'class': 'CS101'
        }
        return student_data

    # 指定请求数据的结构
    @api.expect(student_model)
    # 添加 Swagger 文档中的响应状态码和描述
    @api.doc(responses={201: 'Created'})
    # 指定请求方法为 post
    def post(self):
        # 模拟创建学生
        return {'message': 'Student created'}, 201


# 注册资源与路由
api.add_resource(Student, '/student/<int:student_id>')

if __name__ == '__main__':
    app.run(debug=True)

@api.marshal_with(model) 用于指定返回数据时应用 model 模型，以确保返回的数据符合 Swagger 文档中定义的结构。
@api.expect(model) 用于指定请求数据的结构，确保请求体中的数据符合 model。
@api.doc(responses={}) 用于添加 Swagger 文档中的响应状态码和描述。

访问 http://127.0.0.1:5000/docs 可以看到自动生成的 Swagger UI 文档。可以在 Swagger UI 中直接进行 API 调用，查看接口的响应结果。

总结

创建 Flask 应用并集成 Flask-RESTX
定义数据模型
添加 Swagger 文档描述
查看 Swagger UI 文档