Skip to content

# Home

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.10+

flask-openapi3 is dependent on the following libraries:

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

## Installation

    1

    pip install -U flask-openapi3[swagger]

or

    1

    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`.
- flask-openapi3-plugins Provide OpenAPI UI for flask-openapi3.

To install these dependencies with flask-openapi3:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13

    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.

     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

    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

     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

    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)

## 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.