apiflask的安装

安装

pip install apiflask

example

from apiflask import APIFlask, Schema, abort
from apiflask.fields import Integer, String
from apiflask.validators import Length, OneOf

app = APIFlask(__name__)

pets = [
    {'id': 0, 'name': 'Kitty', 'category': 'cat'},
    {'id': 1, 'name': 'Coco', 'category': 'dog'}
]


class PetIn(Schema):
    name = String(required=True, validate=Length(0, 10))
    category = String(required=True, validate=OneOf(['dog', 'cat']))


class PetOut(Schema):
    id = Integer()
    name = String()
    category = String()


@app.get('/')
def say_hello():
    # 返回字典或列表等同于使用 jsonify()
    return {'message': 'Hello!'}


@app.get('/pets/<int:pet_id>')
@app.output(PetOut)
def get_pet(pet_id):
    if pet_id > len(pets) - 1:
        abort(404)
    # 你也可以直接返回一个 ORM/ODM 模型类实例
    # APIFlask 会将其序列化为 JSON 格式
    return pets[pet_id]


@app.patch('/pets/<int:pet_id>')
@app.input(PetIn(partial=True))
@app.output(PetOut)
def update_pet(pet_id, data):
    # 验证且解析后的请求输入数据会
    # 作为一个字典传递给视图函数
    if pet_id > len(pets) - 1:
        abort(404)
    for attr, value in data.items():
        pets[pet_id][attr] = value
    return pets[pet_id]

运行

flask run --reload

现在访问 http://localhost:5000/docs 查看交互式 API 文档（Swagger UI）：

或者你可以在创建 APIFlask 实例时通过 docs_ui 参数来设置 API 文档 UI (APIFlask 1.1+):

app = APIFlask(__name__, docs_ui='redoc')

支持的 docs_ui 选项（API 文档库）包括：

• swagger-ui（默认值）：Swagger UI
• redoc：Redoc
• elements：Elements
• rapidoc：RapiDoc
• rapipdf：RapiPDF

注意：如果 API 文档页面加载不出来，大概率是因为 API 文档资源文件对应的 CDN 提供商被政府封锁，可以尝试 更换其他 CDN 提供商， 或是 使用本地资源。下面是设置自定义资源 URL 的示例（可直接复制使用）：

# 放到程序实例定义下
app.config['SWAGGER_UI_BUNDLE_JS'] = 'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.11.1/swagger-ui-bundle.min.js'
app.config['SWAGGER_UI_CSS'] = 'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.11.1/swagger-ui.min.css'
app.config['SWAGGER_UI_STANDALONE_PRESET_JS'] = 'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.11.1/swagger-ui-standalone-preset.min.js'
app.config['REDOC_STANDALONE_JS'] = 'https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js'

自动生成的 OpenAPI 规范文件可以在 http://localhost:5000/openapi.json 访问到。你也可以通过 flask spec 命令 获取：

$ flask spec

更多完整的示例程序见 /examples。

和 Flask 的关系

APIFlsak 是 Flask 之上的一层包装。你只需要记住下面几点区别

• 当创建程序实例时，使用 APIFlask 而不是 Flask。
• 当创建蓝本实例时，使用** APIBlueprint** 而不是 Blueprint。
• 当创建类视图时，使用 apiflask.views.MethodView 而不是 flask.views.MethodView。
• APIFlask 提供的 abort() 函数（apiflask.abort）返回 JSON 错误响应。