spectree

What it is and what it does

SpecTree is a Python library that bridges type annotations and OpenAPI specification generation. It uses pydantic models to define request and response schemas, then automatically generates OpenAPI documents and serves them via interactive UI (Redoc, Swagger, or Scalar). The library works as a decorator-based validator that intercepts HTTP requests to your web application, validates query parameters, JSON bodies, headers, and cookies against your pydantic models, and validates responses before they're sent to clients.

The library is framework-agnostic at its core but provides integrations for Flask, Quart, Falcon, and Starlette. You define your data structures once as pydantic BaseModels, decorate your route handlers with @api.validate(), and SpecTree handles both validation and documentation generation. Failed validations return 422 status with structured error details. It supports security schemes (API keys, OAuth2), deprecated endpoints, tags, and custom response codes.

Use it for:

• Build REST APIs with automatic OpenAPI documentation by decorating endpoints with pydantic model validators.
• Validate incoming query strings, JSON payloads, headers, and cookies against strict schemas without manual parsing.
• Generate interactive API documentation (Swagger UI, Redoc, or Scalar) that stays in sync with your code.
• Enforce response validation to catch serialization errors before they reach clients.
• Define API security schemes (API keys, OAuth2) and enforce them per-endpoint or globally.
• Skip boilerplate YAML configuration by deriving OpenAPI specs directly from Python type annotations.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Generates OpenAPI documents and validates HTTP requests and responses using Python type annotations with pydantic, supporting Flask, Quart, Falcon, and Starlette.

Yes. SpecTree is actively maintained, has no known vulnerabilities, and installs with minimal friction. It solves a real problem—keeping API documentation synchronized with code—and does so without requiring separate YAML files. The single pydantic dependency is lightweight and widely used. It's most valuable if you're building REST APIs with one of the four supported frameworks and want automatic OpenAPI generation with request/response validation.

Install

spectree on PyPI

pip install spectree

uv add spectree

poetry add spectree

Installing spectree

Before you install

Low install friction with a single runtime dependency (pydantic). Actively maintained with recent commits and modern Python support (3.10+). No known vulnerabilities.

License in practice

Licensed under Apache-2.0 (permissive), allowing commercial and private use with minimal restrictions.

Quickstart

pip install spectree

from spectree import SpecTree, Response
from pydantic import BaseModel

api = SpecTree('flask')

class QueryModel(BaseModel):
    name: str

@api.validate(query=QueryModel, resp=Response(HTTP_200=None))
def hello(query: QueryModel):
    return {'message': f'Hello {query.name}'}

api.register(app)
# API docs at /apidoc/redoc, /apidoc/swagger, or /apidoc/scalar

Requires Python 3.10 or later. Requires one of the supported web frameworks (Flask, Quart, Falcon, or Starlette) to be installed separately.

Verify before relying

• Whether offline mode (spectree[offline]) works reliably with all supported frameworks and UI options.
• Performance characteristics when validating large request/response payloads or high request volumes.
• Compatibility with frameworks beyond the four explicitly listed (Flask, Quart, Falcon, Starlette).

Package facts

Evidence: spectree-2.0.1-py3-none-any.whl

Tags

More Python Modules packages