{"id":8997,"library":"flask-pydantic-spec","title":"Flask Pydantic Spec","description":"Flask Pydantic Spec is a Python library that simplifies the generation of OpenAPI documentation and the validation of Flask request/response payloads using Pydantic models and Python annotations. It provides decorators to integrate Pydantic validation directly into Flask route functions, enhancing API reliability and maintainability. The library is actively maintained, with frequent minor releases, and the current version is 0.8.7.","status":"active","version":"0.8.7","language":"en","source_language":"en","source_url":"https://github.com/turner-townsend/flask-pydantic-spec","tags":["Flask","Pydantic","OpenAPI","Swagger","API validation","REST","Documentation"],"install":[{"cmd":"pip install flask-pydantic-spec","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core web framework integration.","package":"Flask","optional":false},{"reason":"Required for defining request/response schemas and validation logic. Supports both Pydantic v1 and v2 since v0.8.0.","package":"Pydantic","optional":false}],"imports":[{"symbol":"FlaskPydanticSpec","correct":"from flask_pydantic_spec import FlaskPydanticSpec"},{"note":"Used as a base class for defining incoming request schemas, not Flask's 'request' object.","symbol":"Request","correct":"from flask_pydantic_spec import Request"},{"note":"Used as a base class for defining outgoing response schemas, not Flask's 'Response' object.","symbol":"Response","correct":"from flask_pydantic_spec import Response"},{"note":"Used within Pydantic models to specify query parameters.","symbol":"Query","correct":"from flask_pydantic_spec import Query"},{"note":"Pydantic's base model for schema definition.","symbol":"BaseModel","correct":"from pydantic import BaseModel"},{"note":"Pydantic's utility for field configuration.","symbol":"Field","correct":"from pydantic import Field"}],"quickstart":{"code":"from flask import Flask\nfrom flask_pydantic_spec import FlaskPydanticSpec, Request, Response, Query\nfrom pydantic import BaseModel, Field\n\n# Define Pydantic models for request and response\nclass UserRequest(Request):\n    user_id: int = Field(Query, description=\"ID of the user\")\n\nclass UserResponse(BaseModel):\n    id: int\n    name: str\n    email: str\n\napp = Flask(__name__)\nspec = FlaskPydanticSpec('flask-pydantic-spec', app=app)\nspec.register(app)\n\n@app.route('/user/<int:user_id>')\n@spec.validate(\n    query=UserRequest,\n    resp=Response(HTTP_200=UserResponse)\n)\ndef get_user(user_id):\n    # Access validated query parameters via spec.query\n    # Note: user_id from path param will override if name conflict\n    if spec.query.user_id != user_id:\n        print(f\"Warning: Path ID {user_id} and Query ID {spec.query.user_id} mismatch.\")\n\n    # In a real app, fetch user from DB\n    user_data = {\"id\": user_id, \"name\": f\"User_{user_id}\", \"email\": f\"user{user_id}@example.com\"}\n    return UserResponse(**user_data).model_dump()\n\n# Example of OpenAPI documentation endpoint (auto-generated)\n# Accessible at /swagger or /redoc by default\n\nif __name__ == '__main__':\n    app.run(debug=True)","lang":"python","description":"This quickstart demonstrates how to create a Flask application with `flask-pydantic-spec` to validate incoming query parameters and serialize outgoing JSON responses. It defines Pydantic models for the request's query and the response body. The `@spec.validate` decorator applies the validation rules, and validated data is accessible via `spec.query` or `spec.body` within the route function."},"warnings":[{"fix":"Either downgrade `flask-pydantic-spec` to <0.7.0, upgrade your Pydantic models to v2.x syntax, or upgrade `flask-pydantic-spec` to v0.8.0 or newer which re-introduced support for Pydantic v1 models alongside v2.","message":"Pydantic v1.x support was removed in `flask-pydantic-spec` v0.7.0, making it strictly Pydantic v2.x compatible. If you relied on Pydantic v1.x models, your application would break upon upgrading to v0.7.x.","severity":"breaking","affected_versions":"0.7.x"},{"fix":"Upgrade to `flask-pydantic-spec` v0.8.6 or newer to utilize blueprint integration. For older versions, you'd need to manually register routes or configure the spec object globally.","message":"Blueprint support was added in `flask-pydantic-spec` v0.8.6. Prior versions do not natively support attaching `FlaskPydanticSpec` instances directly to Flask Blueprints.","severity":"gotcha","affected_versions":"<0.8.6"},{"fix":"Ensure `@app.route()` or `@blueprint.route()` is the first decorator applied to your route function, followed by `@spec.validate()`.","message":"The order of decorators matters. Flask's `@app.route()` or `@blueprint.route()` decorator should typically be placed *before* `flask-pydantic-spec`'s `@spec.validate()` decorator.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `flask-pydantic-spec` v0.8.2 or newer to ensure correct OpenAPI 3.1.0 schema generation. Also, ensure your Swagger UI/Redoc versions are compatible with OpenAPI 3.1.0 if using that spec version.","message":"OpenAPI Specification 3.1.0 changed the schema keyword from 'definitions' to '$defs'. While `flask-pydantic-spec` v0.8.2 fixed this internally for its generated specs, older versions (specifically for 'v1 specs') might generate schemas that are not fully compliant with newer OpenAPI 3.1.0 tools or Swagger UI versions.","severity":"deprecated","affected_versions":"<0.8.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install flask-pydantic-spec`.","cause":"The `flask-pydantic-spec` library has not been installed in your Python environment.","error":"ModuleNotFoundError: No module named 'flask_pydantic_spec'"},{"fix":"Check the detailed error message for specific field violations. Adjust your incoming request data or refine your Pydantic model definition to match the expected format.","cause":"The incoming request data (query, body, headers, etc.) does not conform to the Pydantic model defined in your `@spec.validate` decorator.","error":"pydantic.ValidationError: 1 validation error for RequestModelName"},{"fix":"Ensure `spec = FlaskPydanticSpec('app_name', app=app)` is called correctly and `spec.register(app)` is executed before routes are defined or accessed. Also, verify that the arguments passed to `@spec.validate` (e.g., `query`, `resp`) are correctly formed Pydantic models or `Response` objects.","cause":"This often occurs if `@spec.validate` is called with incorrect arguments, or if the `FlaskPydanticSpec` instance (`spec`) has not been properly initialized or registered with the Flask app (e.g., `spec.register(app)` is missing or called too late).","error":"TypeError: 'NoneType' object is not callable"},{"fix":"If on `flask-pydantic-spec` v0.7.x, you must use Pydantic V2 models. If on v0.8.0+, ensure consistency; if using V1 models, ensure they adhere to V1 syntax (e.g., `BaseModel` instead of `pydantic.v2.BaseModel`). Best practice is to upgrade `flask-pydantic-spec` to v0.8.0+ and ensure your Pydantic models are compatible with either V1 or V2 as appropriate for your project setup.","cause":"This can happen if you are using Pydantic V1 models with `flask-pydantic-spec` v0.7.x, which only supported Pydantic V2. Or more generally, if you're mixing Pydantic V1 and V2 syntax when only one version is expected.","error":"TypeError: BaseModel.__init__() got an unexpected keyword argument 'id'"}]}