跳转至

简介

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

test pypi pypistats pypi versions

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

主要特点有：

依赖⚓︎

Python 3.8+

flask-openapi3 依赖以下库：

安装⚓︎

1
pip install -U flask-openapi3

或者

1
conda install -c conda-forge flask-openapi3
可选依赖项

和 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
62
63
from typing import Optional

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: Optional[int] = Field(None, description='Age')


class BookBody(BaseModel):
    age: Optional[int] = 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模板

openapi