{"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":"python","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,"search_vec":"'5.31.0':53 'act':31 'api':24,72 'applic':29 'automat':40 'cadenc':59 'current':50 'direct':26 'document':25,73 'ecosystem':68 'enabl':22 'flask':2,6,20,28,38,66,69 'flask-openapi3':19,37,65 'flask-openapi3-swagger':1,5 'follow':55 'framework':75 'instal':46 'integr':44 'interact':23 'librari':12,48 'openapi':70 'openapi3':3,7,21,39,67 'option':34 'part':61 'plugin':35 'provid':14,41 'python':11 'regular':57 'releas':58 'swagger':4,8,16,42,71 'ui':17,43 'version':52 'web':74 'wider':64 'within':27","created_at":"2026-04-11T09:14:38.027449+00:00","updated_at":"2026-04-16T15:07:34.987121+00:00","problems":[{"fix":"Ensure 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.","cause":"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.","error":"Failed to load API definition"},{"fix":"Ensure `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.","cause":"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.","error":"ModuleNotFoundError: No module named 'flask_openapi3'"},{"fix":"Instead 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.","cause":"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`).","error":"AttributeError: module 'flask_openapi3.request' has no attribute 'method'"},{"fix":"Ensure 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.","cause":"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.","error":"Swagger UI only shows title and no routes documented"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.31.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/luolingchun/flask-openapi3-plugins","docs":"https://luolingchun.github.io/flask-openapi3/latest/Usage/UI_Templates/","changelog":null,"pypi":"https://pypi.org/project/flask-openapi3-swagger/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}