{"id":5627,"library":"flask-openapi3","title":"flask-openapi3","description":"Flask-OpenAPI3 is a web API framework based on Flask, currently at version 4.3.1. It simplifies the generation of REST APIs and OpenAPI documentation (including Swagger UI, ReDoc, and RapiDoc) for Flask projects. It leverages Pydantic for data validation and schema definition, and is actively maintained with frequent updates.","status":"active","version":"4.3.1","language":"python","source_language":"en","source_url":"https://github.com/luolingchun/flask-openapi3","tags":["flask","openapi","swagger","api documentation","pydantic","rest-api"],"install":[{"cmd":"pip install flask-openapi3","lang":"bash","label":"Standard Installation"},{"cmd":"pip install flask-openapi3[swagger,redoc,rapidoc]","lang":"bash","label":"With Common UI Plugins"}],"dependencies":[{"reason":"Core web framework integration.","package":"Flask","optional":false},{"reason":"Data validation and schema definition.","package":"Pydantic","optional":false}],"imports":[{"symbol":"OpenAPI","correct":"from flask_openapi3 import OpenAPI"},{"symbol":"Info","correct":"from flask_openapi3 import Info"},{"symbol":"Tag","correct":"from flask_openapi3 import Tag"},{"note":"Used for defining request/response schemas.","symbol":"BaseModel","correct":"from pydantic import BaseModel"}],"quickstart":{"code":"from flask_openapi3 import Info, Tag, OpenAPI\nfrom pydantic import BaseModel\n\ninfo = Info(title='Book API', version='1.0.0')\napp = OpenAPI(__name__, info=info)\n\nbook_tag = Tag(name='book', description='Book management operations')\n\nclass BookQuery(BaseModel):\n    age: int\n    author: str\n\n@app.get('/book', tags=[book_tag], summary='Get books by query')\ndef get_book(query: BookQuery):\n    \"\"\"Retrieves a list of books based on age and author.\"\"\"\n    return {\n        \"code\": 0,\n        \"message\": \"ok\",\n        \"data\": [\n            {\"bid\": 1, \"age\": query.age, \"author\": query.author},\n            {\"bid\": 2, \"age\": query.age, \"author\": query.author}\n        ]\n    }\n\nif __name__ == '__main__':\n    # Access OpenAPI docs at http://127.0.0.1:5000/openapi\n    app.run(debug=True)","lang":"python","description":"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`."},"warnings":[{"fix":"For v4.x, continue using `flask-openapi3`. For v5+, install `flask-openapi` and update imports from `flask_openapi3` to `flask_openapi`.","message":"The 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.","severity":"breaking","affected_versions":"v5.0.0rc1+"},{"fix":"Upgrade to `flask-openapi3>=4.3.0` to ensure correct handling of Pydantic v2 validation errors.","message":"When 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.","severity":"gotcha","affected_versions":"<4.3.0 when using Pydantic v2"},{"fix":"Upgrade 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.","message":"When 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.","severity":"gotcha","affected_versions":"<4.2.1"},{"fix":"Always navigate to the base `/openapi` path provided by the extension, which then links to the specific UI tools.","message":"The 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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'4.3.1':18 'activ':49 'api':10,25,57,62 'base':12 'current':15 'data':42 'definit':46 'document':28,58 'flask':2,5,14,36,54 'flask-openapi3':1,4 'framework':11 'frequent':52 'generat':22 'includ':29 'leverag':39 'maintain':50 'openapi':27,55 'openapi3':3,6 'project':37 'pydant':40,59 'rapidoc':34 'redoc':32 'rest':24,61 'rest-api':60 'schema':45 'simplifi':20 'swagger':30,56 'ui':31 'updat':53 'valid':43 'version':17 'web':9","created_at":"2026-04-14T03:36:50.064804+00:00","updated_at":"2026-04-16T15:07:32.103242+00:00","problems":[{"fix":"Ensure `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`.","cause":"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`.","error":"ModuleNotFoundError: No module named 'flask_openapi3'"},{"fix":"Ensure 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()`.","cause":"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.","error":"Swagger UI not showing routes"},{"fix":"Import 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.","cause":"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.","error":"AttributeError: module 'flask_openapi3.request' has no attribute 'method'"},{"fix":"When 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.","cause":"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.","error":"TypeError: ModelMetaclass object argument after ** must be a mapping, not Response"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.3.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/luolingchun/flask-openapi","docs":"https://luolingchun.github.io/flask-openapi","changelog":null,"pypi":"https://pypi.org/project/flask-openapi3/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}