Flask-RESTful-Swagger-2.0 使用教程

杜薇剑Dale

于 2025-04-19 07:09:01 发布

阅读量781

点赞数 11

本文链接：https://blog.csdn.net/gitblog_00811/article/details/147344385

版权

Flask-RESTful-Swagger-2.0 使用教程

flask-restful-swagger-2.0 A Swagger spec extractor for flask-restful 项目地址: https://gitcode.com/gh_mirrors/fl/flask-restful-swagger-2.0

1. 项目介绍

Flask-RESTful-Swagger-2.0 是一个开源项目，为 Flask 应用程序提供 Swagger 2.0 规范的支持。它是基于 Flask-RESTful 构建的，允许开发者通过简单的装饰器和模型定义，快速生成 Swagger 文档，使得 API 的测试和交互变得更加直观和便捷。

2. 项目快速启动

首先，确保你已经安装了 Flask 和 Flask-RESTful。接下来，按照以下步骤进行快速启动：

from flask import Flask
from flask_restful_swagger_2 import Api, Swagger

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

# 创建 Swagger 实例
api = Api(app, api_version='0.0', api_spec_url='/api/swagger')

# 定义资源
class UserResource(Resource):
    @swagger.doc({
        'tags': ['user'],
        'description': '获取用户信息',
        'parameters': [
            {
                'name': 'user_id',
                'description': '用户标识',
                'in': 'path',
                'type': 'integer'
            }
        ],
        'responses': {
            '200': {
                'description': '用户信息',
                'schema': {
                    'type': 'object',
                    'properties': {
                        'id': {'type': 'integer'},
                        'name': {'type': 'string'}
                    }
                }
            }
        }
    })
    def get(self, user_id):
        # 返回用户信息
        return {'id': user_id, 'name': 'John Doe'}, 200

# 添加资源到 API
api.add_resource(UserResource, '/api/user/<int:user_id>')

# 运行应用
if __name__ == '__main__':
    app.run(debug=True)

3. 应用案例和最佳实践

定义模型

在 Flask-RESTful-Swagger-2.0 中，你可以定义模型来规范你的响应数据结构。以下是如何定义一个用户模型的例子：

from flask_restful_swagger_2 import Schema

class UserModel(Schema):
    type = 'object'
    properties = {
        'id': {'type': 'integer', 'format': 'int64'},
        'name': {'type': 'string'},
    }
    required = ['name']

使用请求解析器

你可以使用 Flask-RESTful 的请求解析器来解析请求参数，并将其自动添加到 Swagger 文档中：

from flask_restful import reqparse
from flask_restful_swagger_2 import Resource, swagger

class UserResource(Resource):
    post_parser = reqparse.RequestParser()
    post_parser.add_argument('name', type=str, required=True)
    post_parser.add_argument('age', type=int)

    @swagger.doc({
        'tags': ['user'],
        'description': '创建新用户',
        'reqparser': {
            'name': 'user parser',
            'parser': post_parser
        },
        'responses': {
            '201': {
                'description': '用户已创建',
                'schema': UserModel
            }
        }
    })
    def post(self):
        # 处理请求，创建用户
        return {'id': 1, 'name': 'John Doe'}, 201