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.
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, RapiDoc, RapiPdf, Scalar, Elements
-
Data validation: Fast data verification based on Pydantic
Requirements
Python 3.8+
flask-openapi3 is dependent on the following libraries:
Installation
pip install -U flask-openapi3[swagger]or
conda install -c conda-forge flask-openapi3[swagger]Optional dependencies
- [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] ```A 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
```python 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/API Document
Run the simple example, 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.
