Project: flask-openapi3

Generate REST API and OpenAPI documentation for your Flask project.

Project Details

Latest version: 3.0.1
Home Page
PyPI Page: https://pypi.org/project/flask-openapi3/

Project Popularity

PageRank: 0.002287752400577684
Number of downloads: 149517

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:

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

Installation

pip install -U flask-openapi3

conda install -c conda-forge flask-openapi3

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.

openapi openapi-swagger openapi-redoc openapi-RapiDoc