Install & Compatibility
Where this runs
tested against v4.3.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.941s · 36.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.1s · import 0.874s · 36MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAPI
✓ from flask_openapi3 import OpenAPI
Info
✓ from flask_openapi3 import Info
Tag
✓ from flask_openapi3 import Tag
BaseModel
✓ from pydantic import BaseModel
Used for defining request/response schemas.
This example initializes a Flask-OpenAPI3 application, defines a Pydantic model for query parameters, and registers a GET endpoint. The OpenAPI documentation will be automatically generated and accessible at `/openapi`.
from flask_openapi3 import Info, Tag, OpenAPI
from pydantic import BaseModel
info = Info(title='Book API', version='1.0.0')
app = OpenAPI(__name__, info=info)
book_tag = Tag(name='book', description='Book management operations')
class BookQuery(BaseModel):
age: int
author: str
@app.get('/book', tags=[book_tag], summary='Get books by query')
def get_book(query: BookQuery):
"""Retrieves a list of books based on age and author."""
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__':
# Access OpenAPI docs at http://127.0.0.1:5000/openapi
app.run(debug=True)
Debug
Known issues
breakingThe upcoming major version (v5.0.0rc1 and beyond) renames the library from `flask-openapi3` to `flask-openapi`. This will require installing a new package (`pip install flask-openapi`) and updating import statements.fixFor v4.x, continue using `flask-openapi3`. For v5+, install `flask-openapi` and update imports from `flask_openapi3` to `flask_openapi`.
affects: v5.0.0rc1+
gotchaWhen using Pydantic v2 (required `Pydantic>=2.4`), be aware that the `ValidationError` schema changed. Version 4.3.0 of `flask-openapi3` includes a fix for this, so ensure you are on `v4.3.0` or newer for full compatibility.fixUpgrade to `flask-openapi3>=4.3.0` to ensure correct handling of Pydantic v2 validation errors.
affects: <4.3.0 when using Pydantic v2
gotchaWhen registering blueprints, older versions of `flask-openapi3` (prior to 4.2.1) had an issue where `register_api` was not idempotent. Repeated calls could lead to unexpected behavior or duplicate routes.fixUpgrade to `flask-openapi3>=4.2.1`. If upgrading is not possible, ensure `register_api` is only called once per blueprint or handle potential side effects manually.
affects: <4.2.1
gotchaThe generated API documentation (Swagger UI, Redoc, etc.) is typically served under the `/openapi` path (e.g., `http://127.0.0.1:5000/openapi`). Users sometimes expect direct access at `/swagger` or `/redoc`.fixAlways navigate to the base `/openapi` path provided by the extension, which then links to the specific UI tools.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flask_openapi3'
This error occurs either because the `flask-openapi3` package is not installed in the current Python environment, or because a user is trying to import `flask_openapi3` while having version 5.x (or newer) installed, which renamed the package to `flask-openapi`.
fixEnsure `flask-openapi3` is installed using `pip install flask-openapi3`. If using version 5.x or newer, install `pip install flask-openapi` and update import statements from `from flask_openapi3 import OpenAPI` to `from flask_openapi import OpenAPI`.
Swagger UI not showing routes
This typically happens when routes are not properly registered with the `OpenAPI` app instance, or when the `OpenAPI` object is not correctly initialized to scan for routes.
fixEnsure that `OpenAPI(__name__, info=Info(title="API", version="1.0.0"))` is correctly instantiated and that all blueprints or routes intended for documentation are registered with this `app` instance using `app.register_blueprint()`.
AttributeError: module 'flask_openapi3.request' has no attribute 'method'
When using `flask-openapi3`, the `request` object within route handlers is often the Pydantic-validated request body or query parameters, not the raw Flask `request` object. Direct access to `request.method` from `flask_openapi3.request` is incorrect because it's not the standard Flask `request` global.
fixImport the standard Flask `request` object using `from flask import request` and use `request.method` from that imported object instead of trying to access it from the `flask_openapi3` context.
TypeError: ModelMetaclass object argument after ** must be a mapping, not Response
This error occurs when defining a response in `flask-openapi3` with a Pydantic model where the `Response` object itself is passed directly instead of its schema, or due to incorrect keyword arguments passed to the response definition that `flask-openapi3` attempts to interpret as a Pydantic `Response` model.
fixWhen defining responses, ensure you are passing a Pydantic `BaseModel` as the schema or a dictionary representing the OpenAPI Media Type Object, for example: `responses={200: MyPydanticResponseModel}` or `responses={200: {'content': {'application/json': {'schema': MyPydanticResponseModel}}}}`. Also, ensure you are on `flask-openapi3` version 4.2.0 or higher for improved response handling. Upgrade
Version history
4.3.2latest on PyPI · released May 9, 2026
Audit
Dependencies
FlaskrequiredCore web framework integration.
PydanticrequiredData validation and schema definition.