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
Python 3.9+
flask-openapi3 is dependent on the following libraries:
pip install -U flask-openapi3[swagger]or
conda install -c conda-forge flask-openapi3[swagger]Optional 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. - flask-openapi3-plugins Provide OpenAPI UI for flask-openapi3.
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-validator # OpenAPI UI plugins pip install -U flask-openapi3[swagger,redoc,rapidoc,rapipdf,scalar,elements]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)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.
