跳转至

# 简介

为你的 Flask 项目生成 REST API 和 OpenAPI 文档。

Flask OpenAPI3 是一个基于 Flask 的 web API 框架，使用 Pydantic 验证数据，自动生成交互文档。

主要特点有：

- 编码简单： 使用简单易于学习
- 标准的文档规范： 基于开放 API 规范
- 交互式 OpenAPI 文档： Swagger, Redoc, RapiDoc, RapiPdf, Scalar, Elements
- 数据验证： 基于 Pydantic 的快速数据验证

## 依赖

Python 3.10+

flask-openapi3 依赖以下库：

- Flask：用于WEB服务
- Pydantic：用于数据验证

## 安装

    1

    pip install -U flask-openapi3

或者

    1

    conda install -c conda-forge flask-openapi3

可选依赖项

- python-email-validator 支持邮箱验证；
- python-dotenv 在运行 `flask` 命令时启用对 dotenv 环境变量 的支持；
- pyyaml 用于输出 `yaml`格式的 OpenAPI 文档；
- asgiref 允许在定义视图函数时使用 `async def` 和 `await`；
- flask-openapi3-plugins 为 Flask-OpenAPI3 提供 OpenAPI UI.

和 flask-openapi3 一起安装这些依赖:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13

    pip install flask-openapi3[yaml]
    # 或者
    pip install flask-openapi3[async]
    # 或者
    pip install flask-openapi3[dotenv]
    # 或者
    pip install flask-openapi3[email]
    # 或者安装全部
    pip install flask-openapi3[yaml,async,dotenv,email]
    # 或者手动安装
    pip install pyyaml asgiref python-dotenv email-validator
    # OpenAPI UI 插件
    pip install -U flask-openapi3[swagger,redoc,rapidoc,rapipdf,scalar,elements]

## 一个简单的示例

这里有一个简单的示例，更多示例请查看示例。

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33

    from pydantic import BaseModel

    from flask_openapi3 import Info, Tag
    from flask_openapi3 import OpenAPI

    info = Info(title="book API", version="1.0.0")
    app = OpenAPI(__name__, info=info)

    book_tag = Tag(name="book", description="Some Book")

    class BookQuery(BaseModel):
        age: int
        author: str

    @app.get("/book", summary="get books", tags=[book_tag])
    def get_book(query: BookQuery):
        """
        to get all books
        """
        return {
            "code": 0,
            "message": "ok",
            "data": [
                {"bid": 1, "age": query.age, "author": query.author},
                {"bid": 2, "age": query.age, "author": query.author}
            ]
        }

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

基于类的 API 视图示例

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61

    from pydantic import BaseModel, Field

    from flask_openapi3 import OpenAPI, Tag, Info, APIView

    info = Info(title='book API', version='1.0.0')
    app = OpenAPI(__name__, info=info)

    api_view = APIView(url_prefix="/api/v1", view_tags=[Tag(name="book")])

    class BookPath(BaseModel):
        id: int = Field(..., description="book ID")

    class BookQuery(BaseModel):
        age: int | None = Field(None, description='Age')

    class BookBody(BaseModel):
        age: int | None = Field(..., ge=2, le=4, description='Age')
        author: str = Field(None, min_length=2, max_length=4, description='Author')

    @api_view.route("/book")
    class BookListAPIView:
        a = 1

        @api_view.doc(summary="get book list")
        def get(self, query: BookQuery):
            print(self.a)
            return query.model_dump_json()

        @api_view.doc(summary="create book")
        def post(self, body: BookBody):
            """description for a created book"""
            return body.model_dump_json()

    @api_view.route("/book/<id>")
    class BookAPIView:
        @api_view.doc(summary="get book")
        def get(self, path: BookPath):
            print(path)
            return "get"

        @api_view.doc(summary="update book")
        def put(self, path: BookPath):
            print(path)
            return "put"

        @api_view.doc(summary="delete book", deprecated=True)
        def delete(self, path: BookPath):
            print(path)
            return "delete"

    app.register_api_view(api_view)

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

## API 文档

运行简单示例，然后访问 http://127.0.0.1:5000/openapi。

> OpenAPI UI插件是需要手动安装的可选依赖项。

> `pip install -U flask-openapi3[swagger,redoc,rapidoc,rapipdf,scalar,elements]`

> 更多可选UI模板