{"id":2952,"library":"flask-openapi3-swagger","title":"Flask-OpenAPI3-Swagger","description":"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.","status":"active","version":"5.31.0","language":"en","source_language":"en","source_url":"https://github.com/luolingchun/flask-openapi3-plugins/tree/master/flask-openapi3-swagger","tags":["Flask","OpenAPI","Swagger","API Documentation","Web Framework"],"install":[{"cmd":"pip install flask-openapi3-swagger","lang":"bash","label":"Direct installation"},{"cmd":"pip install 'flask-openapi3[swagger]'","lang":"bash","label":"As an optional dependency of flask-openapi3"}],"dependencies":[{"reason":"This package is a plugin for flask-openapi3 and provides its Swagger UI functionality.","package":"flask-openapi3","optional":false}],"imports":[{"note":"Users typically do not import directly from `flask_openapi3_swagger`. Its installation automatically provides the Swagger UI feature to `flask-openapi3`.","symbol":"Swagger UI integration","correct":"The presence of `flask-openapi3-swagger` on the Python path enables Swagger UI when initializing `flask_openapi3.OpenAPI`."},{"note":"The core application and configuration classes come from `flask_openapi3`, not `flask_openapi3_swagger` directly.","wrong":"from flask_openapi3_swagger import OpenAPI","symbol":"OpenAPI, Info, Tag","correct":"from flask_openapi3 import OpenAPI, Info, Tag"}],"quickstart":{"code":"from flask import Flask\nfrom flask_openapi3 import OpenAPI, Info, Tag\nimport os\n\ninfo = Info(title=\"Flask API\", version=\"1.0.0\", description=\"A simple Flask OpenAPI3 application.\")\ntags = [\n    Tag(name=\"hello\", description=\"Hello world endpoints\"),\n]\n\napp = OpenAPI(__name__, info=info, tags=tags)\n\n# Configure Swagger UI path (optional, default is /openapi/swagger)\napp.config[\"OPENAPI_SWAGGER_UI_PATH\"] = \"/swagger-ui\"\n\n\n@app.get(\"/hello\", tags=[\"hello\"])\ndef hello():\n    \"\"\"Say Hello\n    Gets a greeting message.\n    ---\n    responses:\n        200:\n            description: A greeting message.\n    \"\"\"\n    return {\"message\": \"Hello, World!\"}\n\n\nif __name__ == \"__main__\":\n    # Run with `flask run` or `python app.py`\n    # Access Swagger UI at http://127.0.0.1:5000/swagger-ui/\n    app.run(debug=True)","lang":"python","description":"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`)."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"Future major versions of `flask-openapi3` and `flask-openapi3-swagger`"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}