Flask-OpenAPI3-Swagger

5.31.0 · active · verified Sat Apr 11

Flask-OpenAPI3-Swagger is a Python library that provides the Swagger UI for Flask-OpenAPI3, enabling interactive API documentation directly within Flask applications. It acts as an optional plugin for Flask-OpenAPI3, automatically providing Swagger UI integration once installed. The library is currently in version 5.31.0 and follows a regular release cadence as part of the wider Flask-OpenAPI3 ecosystem.

Warnings

gotcha Swagger 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.
Fix: Verify 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`.
gotcha Arguments 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.
Fix: Review 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.
gotcha Swagger 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.
Fix: Explicitly 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.
breaking The 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`.
Fix: Monitor 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.

Install

pip install flask-openapi3-swagger Direct installation
pip install 'flask-openapi3[swagger]' As an optional dependency of flask-openapi3

Imports

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
```
The core application and configuration classes come from `flask_openapi3`, not `flask_openapi3_swagger` directly.

Quickstart

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)

view raw JSON →