SpecTree

class spectree.spec.SpecTree[source]

Interface

Parameters:

  • backend_name (str) – choose from (‘flask’, ‘quart’, ‘falcon’, ‘falcon-asgi’, ‘starlette’)

  • backend – a backend that inherit SpecTree.plugins.base.BasePlugin, this will override the backend_name if provided

  • app – backend framework application instance (can be registered later)

  • before – a callback function of the form spectree.utils.default_before_handler() func(req, resp, req_validation_error, instance, model_adapter) that will be called after the request validation before the endpoint function

  • after – a callback function of the form spectree.utils.default_after_handler() func(req, resp, resp_validation_error, instance, model_adapter) that will be called after the response validation

  • validation_error_status – The default response status code to use in the event of a validation error. This value can be overridden for specific endpoints if needed.

  • validation_error_model – The default validation error type to be shown in the generated OpenAPI frontend. Make sure it’s derived from the model adapter (including the ValidationError).

  • naming_strategy – A callable that receives a model class and returns the top-level component schema name used in the OpenAPI document. For example, lambda model: model.__name__.lower().

  • nested_naming_strategy – A callable that receives (parent, child) schema names and returns the component schema name for nested models lifted from $defs. The default includes the parent name to avoid collisions. To share nested models by child name, use lambda _parent, child: child.

  • model_adapter – adapter for validation and OpenAPI JSON schema generation. Choose from the spectree.model_adapter. If not set, will use pydantic.

  • kwargs – init spectree.config.Configuration, they can also be configured through the environment variables with prefix spectree_

__init__(backend_name: str = 'base', backend: ~typing.Type[~spectree.plugins.base.BasePlugin] | None = None, app: ~typing.Any = None, before: ~typing.Callable[[~typing.Any, ~typing.Any, Exception | None, ~typing.Any, ~spectree.model_adapter.protocol.ModelAdapter[~typing.Any, Exception, ~typing.Any]], ~typing.Any] = <function default_before_handler>, after: ~typing.Callable[[~typing.Any, ~typing.Any, Exception | None, ~typing.Any, ~spectree.model_adapter.protocol.ModelAdapter[~typing.Any, Exception, ~typing.Any]], ~typing.Any] = <function default_after_handler>, validation_error_status: int = 422, validation_error_model: type[~typing.Any] | None = None, naming_strategy: ~typing.Callable[[type[~typing.Any]], str] = <function get_model_key>, nested_naming_strategy: ~typing.Callable[[str, str], str] = <function get_nested_key>, model_adapter: ~spectree.model_adapter.protocol.ModelAdapter[~typing.Any, Exception, ~typing.Any] | None = None, **kwargs: ~typing.Any)[source]
bypass(func: Callable)[source]

bypass rules for routes (mode defined in config)

Normal:

collect all the routes exclude those decorated by other SpecTree instance

Greedy:

collect all the routes

Strict:

collect all the routes decorated by this instance

register(app: Any)[source]

register to backend application

This will be automatically triggered if the app is passed into the init step.

property spec

get the OpenAPI spec

validate(query: type[Any] | None = None, json: type[Any] | None = None, form: type[Any] | None = None, headers: type[Any] | None = None, cookies: type[Any] | None = None, resp: Response | None = None, tags: Sequence = (), security: Any = None, deprecated: bool = False, before: Callable[[Any, Any, Exception | None, Any, ModelAdapter[Any, Exception, Any]], Any] | None = None, after: Callable[[Any, Any, Exception | None, Any, ModelAdapter[Any, Exception, Any]], Any] | None = None, validation_error_status: int = 0, path_parameter_descriptions: Mapping[str, str] | None = None, skip_validation: bool = False, operation_id: str | None = None, force_resp_serialize: bool = False) → Callable[source]

  • validate query, json, headers in request

  • validate response body and status code

  • add tags to this API route

  • add security to this API route

Parameters:

  • query – model class for query params in the URI, like ?name=value

  • json – model class for a JSON request body

  • form – model class for a form-data request body

  • headers – model class for validating request headers

  • cookies – model class for validating request cookies

  • resp – spectree.Response

  • tags – a tuple of strings or spectree.models.Tag

  • security – dict with security config for current route and method

  • deprecated – bool, if endpoint is marked as deprecated

  • before – spectree.utils.default_before_handler() for specific endpoint

  • after – spectree.utils.default_after_handler() for specific endpoint

  • validation_error_status – The response status code to use for the specific endpoint, in the event of a validation error. If not specified, the global validation_error_status is used instead, defined in spectree.spec.SpecTree().

  • path_parameter_descriptions – A dictionary of path parameter names and their description.

  • skip_validation – If set to True, the endpoint will skip request / response validations.

  • operation_id – a string override for operationId for the given endpoint

Force_resp_serialize:

Always return the serialized result of the validated response. Requires skip_validation to be False.