flask-openapi3 4.0.0.dev0

Generate REST API and OpenAPI documentation for your Flask project.

Generate REST API and OpenAPI documentation for your Flask project.

This branch is in development preview state.

Flask OpenAPI3 is a web API framework based on Flask. It uses Pydantic to verify data and automatic generation of interaction documentation: Swagger, ReDoc, RapiDoc, etc.

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, etc.

• 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:

• Flask for the web app.
• Pydantic for the data validation.

Installation

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 flask commands.
• pyyaml is used to output the OpenAPI document in yaml format.
• asgiref allows views to be defined with async def and use await.

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

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

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.

Swagger, Redoc, RapiDoc are optional dependencies that require manual installation.

pip install -U flask-openapi3[swagger,redoc,rapidoc]

More optional ui templates goto the document about UI_Templates.