flask-openapi

You can extend the OpenAPI Parameter Object by using the json_schema_extra argument within Pydantic's Field. This allows you to add metadata like example or deprecated to your generated documentation.

Example usage:

• json_schema_extra={'example': 3}
• json_schema_extra={'deprecated': True}

from pydantic import BaseModel, Field

class BookQuery(BaseModel):
    # Adds an example to the OpenAPI spec
    age: int = Field(..., ge=2, le=4, description='Age', json_schema_extra={"example": 3})
    
    # Marks the field as deprecated in the OpenAPI spec
    author: str = Field(None, description='Author', json_schema_extra={"deprecated": True})

The flask_openapi.APIBlueprint class is the primary mechanism for defining API routes that are automatically documented using the OpenAPI specification. Instead of using standard Flask Blueprint objects, you use APIBlueprint to associate metadata (like descriptions, parameters, and response schemas) directly with your route definitions. This ensures that your Flask application's routing logic and its OpenAPI documentation remain synchronized.

from flask_openapi import APIBlueprint

# Create an APIBlueprint instead of a standard Flask Blueprint
api_bp = APIBlueprint("my_api", __name__)

@api_bp.route("/hello", methods=["GET"])
def hello():
    return {"message": "world"}

The operation_id is used to uniquely identify an API operation. By default, it is generated automatically. You can set it manually via the operation_id parameter or globally using an operation_id_callback in the OpenAPI, APIBlueprint, or APIView constructor.

# Manual setting
@app.get('/book/<int:bid>', operation_id="get_book_id")
def get_book(path: BookPath):
    ...

# Custom callback for all operations in a Blueprint
def get_operation_id_for_path(*, bp_name: str = None, name: str, path: str, method: str) -> str:
    return name

api = APIBlueprint('book', __name__, operation_id_callback=get_operation_id_for_path)

You can nest APIBlueprint instances within one another. An APIBlueprint can register another APIBlueprint using its own register_api method, allowing for hierarchical route organization.

from flask_openapi import OpenAPI, APIBlueprint

app = OpenAPI(__name__)

api = APIBlueprint('book', __name__, url_prefix='/api/book')
api_english = APIBlueprint('english', __name__)
api_chinese = APIBlueprint('chinese', __name__)

@api_english.post('/english')
def create_english_book():
    return {"message": "english"}

@api_chinese.post('/chinese')
def create_chinese_book():
    return {"message": "chinese"}

# Register nested blueprints to the parent blueprint
api.register_api(api_english)
api.register_api(api_chinese)

# Register the parent blueprint to the app
app.register_api(api)

if __name__ == '__main__':
    app.run(debug=True)

Documentation for an API can be provided in two ways:

1. Docstrings: The first line of the view function's docstring is treated as the summary, and the subsequent lines are the description.
2. Keyword Arguments: You can explicitly pass summary and description to the route decorator. If provided, these keyword arguments take precedence over the docstring.

# Using docstrings
@app.get('/book/<int:bid>')
def get_book(path: BookPath):
    """Get book
    Get some book by id
    """
    return {}

# Using keyword arguments (takes precedence)
@app.get('/book/<int:bid>', summary="new summary", description='new description')
def get_book(path: BookPath):
    """Get book
    This docstring will be ignored for summary/description
    """
    return {}

For organizing your application into modules, use APIBlueprint (based on Flask Blueprints). Note that you must use app.register_api(api) instead of the standard Flask register_blueprint method to register an APIBlueprint.

from flask_openapi import OpenAPI, APIBlueprint

app = OpenAPI(__name__)

api = APIBlueprint('book', __name__, url_prefix='/api')

@api.post('/book')
def create_book():
    return {"message": "success"}

# Use register_api instead of register_blueprint
app.register_api(api)

if __name__ == '__main__':
    app.run()

When using Pydantic BaseModel within flask-openapi, you might want to use the original field names instead of their defined aliases (for example, when generating API responses). You can control this behavior by setting by_alias=False in the model_config dictionary of your model class.

class MessageResponse(BaseModel):
    message: str = Field(..., description="The message")
    metadata: dict[str, str] = Field(alias="metadata_")

    model_config = dict(
        by_alias=False
    )

The APIBlueprint class allows you to group related routes, tags, security requirements, and responses into a modular unit. This is useful for large projects. After defining the blueprint, you must register it with the main application using app.register_api(blueprint).

from flask_openapi import APIBlueprint

api = APIBlueprint(
    "/book",
    __name__,
    url_prefix="/api",
    abp_tags=[tag],
    abp_security=security,
    abp_responses={"401": Unauthorized}
)

@api.get("/list")
def list_books():
    return {"code": 0, "message": "ok"}

# Register with the main app
app.register_api(api)

To define asynchronous endpoints, use the async def syntax.

Requirement: You must manually install asgiref to support async functionality.

pip install flask-openapi[async]

# or
pip install asgiref

@app.post('/open/api')
async def post_openapi(body: Query):
    print(body)
    return 'POST, OpenAPI!'

To improve JSON serialization performance, you can replace the default Flask JSON provider with a custom OrJSONProvider using the orjson library. This involves subclassing flask.json.provider.JSONProvider, implementing dumps and loads, and assigning the provider instance to app.json.

import orjson
from flask.json.provider import JSONProvider

class OrJSONProvider(JSONProvider):
    # https://github.com/ijl/orjson#option
    option = orjson.OPT_INDENT_2

    def dumps(self, obj, **kwargs):
        return orjson.dumps(obj, option=self.option).decode()

    def loads(self, s, **kwargs):
        return orjson.loads(s)
    
app = OpenAPI(__name__, info=info)
# use orjson
orjson_provider = OrJSONProvider(app)
app.json = orjson_provider