Generate REST API and OpenAPI documentation for your Flask project.
Flask OpenAPI3 is a web API framework based on Flask. It uses Pydantic to verify data and automatic generation of interaction documentation: Swagger, ReDoc and RapiDoc.
The key features are:
-
Easy to code: Easy to use and easy to learn
-
Standard document specification: Based on OpenAPI Specification
-
Interactive OpenAPI documentation: Swagger, Redoc and RapiDoc
-
Data validation: Fast data verification based on Pydantic
-
Authorization: Support to reload authorizations in Swagger UI
Requirements
Python 3.8+
flask-openapi3 is dependent on the following libraries:
Installation
pip install -U flask-openapi3or
conda install -c conda-forge flask-openapi3Optional dependencies
- python-email-validator supports email verification.
- python-dotenv enables support for Environment Variables From dotenv when running
flaskcommands. - pyyaml is used to output the OpenAPI document in yaml format.
- asgiref allows views to be defined with
async defand useawait.
To install these dependencies with flask-openapi3:
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-validatorA Simple Example
Here's a simple example, further go to the Example.
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)Class-based API View Example
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 Document
Run the simple example, and go to http://127.0.0.1:5000/openapi.
You will see the documentation: Swagger, Redoc and RapiDoc.
