Install & Compatibility
Where this runs
tested against v5.31.0 · 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.000s · 35MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.2s · import 0.000s · 35MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Swagger UI integration
✓ The presence of `flask-openapi3-swagger` on the Python path enables Swagger UI when initializing `flask_openapi3.OpenAPI`.
Users typically do not import directly from `flask_openapi3_swagger`. Its installation automatically provides the Swagger UI feature to `flask-openapi3`.
OpenAPI, Info, Tag
✓ from flask_openapi3 import OpenAPI, Info, Tag
✗ from flask_openapi3_swagger import OpenAPI
The core application and configuration classes come from `flask_openapi3`, not `flask_openapi3_swagger` directly.
This quickstart demonstrates how to set up a basic Flask application with `flask-openapi3` and enable Swagger UI. Once `flask-openapi3-swagger` is installed, simply configuring the `OpenAPI` app from `flask_openapi3` automatically makes the Swagger UI available at the specified path (or default `/openapi/swagger`).
from flask import Flask
from flask_openapi3 import OpenAPI, Info, Tag
import os
info = Info(title="Flask API", version="1.0.0", description="A simple Flask OpenAPI3 application.")
tags = [
Tag(name="hello", description="Hello world endpoints"),
]
app = OpenAPI(__name__, info=info, tags=tags)
# Configure Swagger UI path (optional, default is /openapi/swagger)
app.config["OPENAPI_SWAGGER_UI_PATH"] = "/swagger-ui"
@app.get("/hello", tags=["hello"])
def hello():
"""Say Hello
Gets a greeting message.
---
responses:
200:
description: A greeting message.
"""
return {"message": "Hello, World!"}
if __name__ == "__main__":
# Run with `flask run` or `python app.py`
# Access Swagger UI at http://127.0.0.1:5000/swagger-ui/
app.run(debug=True)
Debug
Known issues
gotchaSwagger UI does not display routes or documentation: This often occurs when the `Info` object is not correctly provided during the `OpenAPI` app initialization, or if blueprints are not properly registered with the `OpenAPI` instance. Ensure your routes have docstrings formatted correctly for OpenAPI parsing.fixVerify that `Info` is passed to `OpenAPI(..., info=info, ...)`, and that all relevant `Blueprint` instances are registered with the `app` object created by `flask_openapi3.OpenAPI`.
affects: All versions
gotchaArguments passed by other decorators (e.g., dependency injection, authentication) are removed from views by `flask-openapi3`: `flask-openapi3`'s internal request validation might incorrectly strip `kwargs` intended for decorated views, breaking functionality like `flask-login` or custom dependency injection.fixReview the call chain when using multiple decorators. Consider adjusting the order of decorators or, if possible, implementing custom argument handling within `flask-openapi3` if it exposes extension points for argument processing. Refer to `flask-openapi3`'s GitHub issues for potential workarounds or fixes related to argument handling in decorated views.
affects: All versions
gotchaSwagger UI not accessible or incorrect version loaded: If `OPENAPI_SWAGGER_UI_PATH` or `OPENAPI_SWAGGER_UI_VERSION` (or similar configuration settings for `flask-openapi3`) are not set correctly, the Swagger UI might not be found at the expected URL or might load an outdated CDN version.fixExplicitly configure `app.config["OPENAPI_SWAGGER_UI_PATH"]` and `app.config["OPENAPI_SWAGGER_UI_VERSION"]` (or `OPENAPI_SWAGGER_UI_URL`) to ensure the correct path and CDN version are used for the Swagger UI.
affects: All versions
breakingThe parent library `flask-openapi3` might be renamed to `flask-openapi`: There's an open discussion regarding renaming `flask-openapi3` to `flask-openapi`. If this change is implemented, it would likely result in breaking changes for imports and potentially package names for dependent libraries like `flask-openapi3-swagger`.fixMonitor the official `flask-openapi3` GitHub repository for announcements regarding breaking changes and migration guides for future major versions. Be prepared to update import paths and package names if the renaming occurs.
affects: Future major versions of `flask-openapi3` and `flask-openapi3-swagger`
Errors
Common errors & fixes
Failed to load API definition
This error often occurs when the Swagger UI cannot fetch the OpenAPI specification (usually `openapi.json` or `openapi.yaml`) from the expected endpoint, leading to an empty or incomplete display. This can be due to incorrect `API_URL` configuration, the spec file not being served, or CORS issues.
fixEnsure that your `OpenAPI` instance is correctly initialized, your Flask application is running, and the API documentation is accessible at the default `/openapi` path or your configured path. Verify that the `API_URL` points to a valid JSON or YAML specification being served by your Flask app. For `flask-openapi3`, the OpenAPI spec is usually served at `/openapi/openapi.json` by default. If manually serving, ensure CORS headers are correctly set if the UI is accessed from a different origin.
ModuleNotFoundError: No module named 'flask_openapi3'
This error indicates that the Python interpreter cannot find the `flask_openapi3` package, which `flask-openapi3-swagger` depends on. This typically happens if the package was not installed, was installed in a different environment, or there's a typo in the import statement.
fixEnsure `flask-openapi3` (and implicitly `flask-openapi3-swagger`) is installed in your active Python environment. Use `pip install -U flask-openapi3[swagger]` to install both the core library and the Swagger UI plugin. Verify your virtual environment is activated and Python path is correct.
AttributeError: module 'flask_openapi3.request' has no attribute 'method'
When migrating from plain Flask to `flask-openapi3`, the `request` object handled by `flask-openapi3` views does not directly expose the `method` attribute in the same way as Flask's global `request` object. `flask-openapi3` processes requests based on the HTTP method decorators (e.g., `@app.post`, `@app.get`).
fixInstead of checking `request.method`, define separate view functions or methods for each HTTP verb using the appropriate `flask-openapi3` decorators (e.g., `@app.get('/path')`, `@app.post('/path')`). The framework handles routing based on these decorators, making the explicit `request.method` check redundant for OpenAPI-defined routes. Swagger UI only shows title and no routes documented
This problem occurs when the Swagger UI interface loads successfully, but the defined API endpoints and their documentation (paths, parameters, responses) are not being correctly generated or recognized by `flask-openapi3`. This can stem from blueprints not being registered with the `OpenAPI` app instance, or routes not being properly decorated with OpenAPI specification details.
fixEnsure that all blueprints containing your API routes are registered with the `OpenAPI` application instance using `app.register_blueprint()`. Also, verify that your routes are correctly decorated with OpenAPI-specific decorators (e.g., `doc` decorator for descriptions, `tags` for grouping) and that request/response schemas (often Pydantic models) are defined and linked appropriately to your endpoints.
Upgrade
Version history
5.31.0latest on PyPI · released Dec 12, 2025
Audit
Dependencies
flask-openapi3requiredThis package is a plugin for flask-openapi3 and provides its Swagger UI functionality.