{"id":7737,"library":"spectree","title":"Spectree","description":"Spectree is a Python library that helps generate OpenAPI documents and validate requests and responses using Python type annotations. It leverages Pydantic for data model definitions and supports various web frameworks like Flask, Quart, Falcon, and Starlette. The library is actively maintained, with the current version being 2.0.1, and typically releases minor fixes after major version updates.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/0b01001001/spectree","tags":["openapi","pydantic","api validation","web frameworks","flask","quart","falcon","starlette","documentation generation"],"install":[{"cmd":"pip install spectree","lang":"bash","label":"Default Installation"},{"cmd":"pip install spectree[email]","lang":"bash","label":"With email validation"}],"dependencies":[{"reason":"Core dependency for defining data models and validation schemas. Spectree v2.0.0+ requires Pydantic v2.","package":"pydantic","optional":false},{"reason":"Required for Flask integration if using 'flask' backend. Choose your web framework backend accordingly.","package":"flask","optional":true},{"reason":"Required for Quart integration if using 'quart' backend.","package":"quart","optional":true},{"reason":"Required for Falcon integration if using 'falcon' or 'falcon-asgi' backend.","package":"falcon","optional":true},{"reason":"Required for Starlette integration if using 'starlette' backend.","package":"starlette","optional":true}],"imports":[{"note":"While `SpecTree` is defined in `spectree.spec`, the public API exports it directly from `spectree`.","wrong":"from spectree.spec import SpecTree","symbol":"SpecTree","correct":"from spectree import SpecTree"},{"note":"`spectree.Response` is for OpenAPI schema declaration, not the web framework's HTTP response object.","wrong":"from flask import Response","symbol":"Response","correct":"from spectree import Response"},{"note":"Spectree v2.0.0+ is incompatible with Pydantic v1. Ensure you import from `pydantic` (Pydantic v2) directly.","wrong":"from pydantic.v1 import BaseModel","symbol":"BaseModel","correct":"from pydantic import BaseModel"}],"quickstart":{"code":"from flask import Flask, request\nfrom pydantic import BaseModel, Field\nfrom spectree import SpecTree, Response\n\napp = Flask(__name__)\napi = SpecTree('flask', app=app, title='User API', version='1.0.0')\n\nclass UserQuery(BaseModel):\n    name: str = Field(..., description='User name')\n    age: int = Field(..., gt=0, lt=150, description='User age')\n\nclass UserResponse(BaseModel):\n    message: str\n    user_id: int\n\n@app.route('/user', methods=['POST'])\n@api.validate(query=UserQuery, resp=Response(HTTP_200=UserResponse), tags=['User'])\ndef create_user():\n    # The validated 'query' data is available in request.context.query\n    user_data = request.context.query\n    user_id = 123 # Simulate user creation\n    return {'message': f'User {user_data.name} created', 'user_id': user_id}\n\n# Access OpenAPI docs at /apidoc/redoc, /apidoc/swagger, or /apidoc/scalar\n\n# To run: FLASK_APP=your_app_file.py flask run","lang":"python","description":"This quickstart demonstrates how to integrate `spectree` with Flask to validate incoming query parameters and define the response schema using Pydantic models. It sets up an API endpoint that creates a user and automatically generates OpenAPI documentation."},"warnings":[{"fix":"Upgrade Pydantic to v2 (`pip install -U pydantic`) and ensure your project runs on Python 3.10 or newer. If you must use Pydantic v1, pin `spectree` to `<2.0.0` (e.g., `pip install 'spectree<2'`).","message":"Spectree v2.0.0 introduced breaking changes by dropping support for Pydantic v1 and Python 3.9. Your application will fail to run if you upgrade spectree to v2+ while still using Pydantic v1 or Python 3.9.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Avoid mixing Pydantic v1 and v2 models. If migrating, ensure all models are converted to Pydantic v2. Use tools like `bump-pydantic` to aid in migration if your codebase is large.","message":"Mixing Pydantic v1 and v2 models in the same application, or passing a Pydantic v1 model as an attribute to a Pydantic v2 model, can lead to runtime `ValidationError`s that are difficult to debug.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"For optional fields that should have `None` as a default, explicitly set `Field(default=None)` or assign `None` as the default value in your Pydantic `BaseModel`. Example: `my_field: Optional[str] = None` or `my_field: Optional[str] = Field(default=None)`.","message":"In Pydantic v2 (required by `spectree` v2+), fields annotated with `typing.Optional[Type]` are now 'required but can be `None`' unless a default value (e.g., `None`) is explicitly provided. This is a change from Pydantic v1 behavior.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade Pydantic to v2 (`pip install -U pydantic`) and update your Pydantic model imports from `pydantic.v1` to `pydantic`. If you need Pydantic v1, you must downgrade `spectree` to a version before 2.0.0 (e.g., `pip install 'spectree<2'`).","cause":"Your application is attempting to import `pydantic.v1.BaseModel` (or other v1 components) while `spectree` v2+ is installed, which expects Pydantic v2.","error":"ModuleNotFoundError: No module named 'pydantic.v1'"},{"fix":"Ensure that any Pydantic fields you intend to be truly optional (i.e., not present in the input) are explicitly given a default value of `None`. Example: `my_field: Optional[str] = None`.","cause":"In Pydantic v2, `Optional[Type]` fields without an explicit `None` default are treated as required fields that can accept `None`. If the input JSON omits this field, Pydantic raises an error.","error":"TypeError: 'NoneType' object is not callable (or similar related to Optional fields in Pydantic v2)"},{"fix":"Ensure that all path parameters in your route string are present as annotated arguments in your function signature, e.g., `@app.route('/user/<int:user_id>') def get_user(user_id: int):`. Spectree uses these annotations to generate the OpenAPI path parameters.","cause":"You have defined a path parameter in your framework's route (e.g., Flask's `<user_id>`) but have not included it as a type-hinted parameter in your decorated endpoint function, or `spectree` could not correctly parse it.","error":"spectree.exceptions.InvalidPathParameter: Parameter 'user_id' in path '/user/<user_id>' is not annotated in endpoint 'get_user'"}]}