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
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
<div align="center">
<a href="https://luolingchun.github.io/flask-openapi3/" target="_blank">
<img class="off-glb" src="./images/logo-text.svg"
width="60%" height="auto" alt="logo">
</a>
</div>
<p align="center">
<em>Generate REST API and OpenAPI documentation for your Flask project.</em>
</p>
**Flask OpenAPI3** is a web API framework based on **Flask**. It uses **Pydantic** to verify data and automatic
generation of interaction documentation.
The key features are:
- **Easy to code:** Easy to use and easy to learn
- **Standard document specification:** Based on [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0)
- **Interactive OpenAPI documentation:** [Swagger](https://github.com/swagger-api/swagger-ui), [Redoc](https://github.com/Redocly/redoc), [RapiDoc](https://github.com/rapi-doc/RapiDoc), [RapiPdf](https://mrin9.github.io/RapiPdf/), [Scalar](https://github.com/scalar/scalar), [Elements](https://github.com/stoplightio/elements)
- **Data validation:** Fast data verification based on [Pydantic](https://github.com/pydantic/pydantic)
## Requirements
Python 3.10+
flask-openapi3 is dependent on the following libraries:
- [Flask](https://github.com/pallets/flask) for the web app.
- [Pydantic](https://github.com/pydantic/pydantic) for the data validation.
## Installation
```bash
pip install -U flask-openapi3[swagger]
```
or
```bash
conda install -c conda-forge flask-openapi3[swagger]
```
<details markdown="block">
<summary>Optional dependencies</summary>
- [python-email-validator](https://github.com/JoshData/python-email-validator) supports email verification.
- [python-dotenv](https://github.com/theskumar/python-dotenv#readme) enables support
for [Environment Variables From dotenv](https://flask.palletsprojects.com/en/latest/cli/#dotenv) when running `flask`
commands.
- [pyyaml](https://github.com/yaml/pyyaml) is used to output the OpenAPI document in yaml format.
- [asgiref](https://github.com/django/asgiref) allows views to be defined with `async def` and use `await`.
- [flask-openapi3-plugins](https://github.com/luolingchun/flask-openapi3-plugins) Provide OpenAPI UI for flask-openapi3.
To install these dependencies with flask-openapi3:
```bash
pip install flask-openapi3[yaml]
# or
pip install flask-openapi3[async]
# or
pip install flask-openapi3[dotenv]
# or
pip install flask-openapi3[email]
# or all
pip install flask-openapi3[yaml,async,dotenv,email]
# or manually
pip install pyyaml asgiref python-dotenv email-validator
# OpenAPI UI plugins
pip install -U flask-openapi3[swagger,redoc,rapidoc,rapipdf,scalar,elements]
```
</details>
## A Simple Example
Here's a simple example, further go to the [Example](https://luolingchun.github.io/flask-openapi3/latest/Example/).
```python
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)
```
<details>
<summary>Class-based API View Example</summary>
```python
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)
```
</details>
## API Document
Run the [simple example](https://github.com/luolingchun/flask-openapi3/blob/master/examples/simple_demo.py), and go to http://127.0.0.1:5000/openapi.
> OpenAPI UI plugins are optional dependencies that require manual installation.
>
> `pip install -U flask-openapi3[swagger,redoc,rapidoc,rapipdf,scalar,elements]`
>
> More optional ui templates goto the document
> about [UI_Templates](https://luolingchun.github.io/flask-openapi3/latest/Usage/UI_Templates/).
|
