spakky-fastapi¶

FastAPI 통합 — 라우트 데코레이터, 자동 엔드포인트 등록

스테레오타입¶

`spakky.plugins.fastapi.stereotypes.api_controller` ¶

API controller stereotype for FastAPI route grouping.

Provides the @ApiController stereotype for marking classes as FastAPI REST controllers with automatic route registration and prefix configuration.

`ApiController(prefix, tags=None, *, name='', scope=Scope.SINGLETON)` `dataclass` ¶

Bases: Controller

Stereotype for FastAPI REST API controllers.

Marks a class as an API controller with automatic route registration. Methods decorated with @get, @post, etc. will be registered as FastAPI endpoints with the specified prefix.

Attributes:

Name	Type	Description
`prefix`	`str`	URL prefix for all routes in this controller.
`tags`	`list[str \| Enum] \| None`	OpenAPI tags for grouping endpoints in documentation.

`prefix` `instance-attribute` ¶

URL prefix prepended to all routes in this controller.

`tags = None` `class-attribute` `instance-attribute` ¶

OpenAPI tags for grouping and organizing endpoints in documentation.

options: show_root_heading: false

라우트¶

`spakky.plugins.fastapi.routes.route` ¶

Base route decorator and configuration for FastAPI endpoints.

Provides the core @route decorator and Route annotation class that can be used to mark controller methods as API endpoints with full FastAPI configuration.

`HTTPMethod` ¶

Bases: str, Enum

HTTP methods supported by FastAPI routes.

`repr()` ¶

Return the method value for display.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/route.py

def __repr__(self) -> str:
    """Return the method value for display."""
    return self.value

Route(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, methods=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) `dataclass` ¶

Bases: FunctionAnnotation

Function annotation for marking methods as API routes.

Stores all FastAPI route configuration including path, HTTP methods, response models, and OpenAPI documentation settings.

Attributes:

Name	Type	Description
`path`	`str`	The URL path for this route.
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.
`status_code`	`int \| None`	HTTP status code for successful responses.
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.
`summary`	`str \| None`	Short summary for OpenAPI documentation.
`description`	`str \| None`	Detailed description for OpenAPI documentation.
`response_description`	`str`	Description of successful response.
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.
`methods`	`set[HTTPMethod] \| list[HTTPMethod] \| None`	HTTP methods this route handles.
`operation_id`	`str \| None`	Custom OpenAPI operation ID.
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.
`response_model_by_alias`	`bool`	Use field aliases in response.
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.
`response_model_exclude_none`	`bool`	Exclude None values from response.
`include_in_schema`	`bool`	Include in OpenAPI schema.
`response_class`	`type[Response]`	FastAPI response class to use.
`name`	`str \| None`	Display name for the route.
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.

route(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, methods=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) ¶

Decorator to mark a controller method as an API route.

Attaches route configuration to the method which will be registered by the RegisterRoutesPostProcessor during container initialization.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this route.	required
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.	`None`
`status_code`	`int \| None`	HTTP status code for successful responses.	`None`
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`
`summary`	`str \| None`	Short summary for OpenAPI documentation.	`None`
`description`	`str \| None`	Detailed description for OpenAPI documentation.	`None`
`response_description`	`str`	Description of successful response.	`'Successful Response'`
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.	`None`
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.	`None`
`methods`	`set[HTTPMethod] \| list[HTTPMethod] \| None`	HTTP methods this route handles.	`None`
`operation_id`	`str \| None`	Custom OpenAPI operation ID.	`None`
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.	`None`
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.	`None`
`response_model_by_alias`	`bool`	Use field aliases in response.	`True`
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.	`False`
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.	`False`
`response_model_exclude_none`	`bool`	Exclude None values from response.	`False`
`include_in_schema`	`bool`	Include in OpenAPI schema.	`True`
`response_class`	`type[Response]`	FastAPI response class to use.	`JSONResponse`
`name`	`str \| None`	Display name for the route.	`None`
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.	`None`
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.	`None`
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that attaches the route configuration.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/route.py

def route(
    path: str,
    response_model: type[Any] | None = None,
    status_code: int | None = None,
    tags: list[str] | None = None,
    dependencies: Sequence[params.Depends] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    methods: set[HTTPMethod] | list[HTTPMethod] | None = None,
    operation_id: str | None = None,
    response_model_include: SetIntStr | DictIntStrAny | None = None,
    response_model_exclude: SetIntStr | DictIntStrAny | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    include_in_schema: bool = True,
    response_class: type[Response] = JSONResponse,
    name: str | None = None,
    route_class_override: type[APIRoute] | None = None,
    callbacks: list[StarletteRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as an API route.

    Attaches route configuration to the method which will be registered by
    the RegisterRoutesPostProcessor during container initialization.

    Args:
        path: The URL path for this route.
        response_model: Pydantic model for response serialization.
        status_code: HTTP status code for successful responses.
        tags: OpenAPI tags for grouping endpoints.
        dependencies: FastAPI dependencies to inject.
        summary: Short summary for OpenAPI documentation.
        description: Detailed description for OpenAPI documentation.
        response_description: Description of successful response.
        responses: Additional response schemas for OpenAPI.
        deprecated: Whether this endpoint is deprecated.
        methods: HTTP methods this route handles.
        operation_id: Custom OpenAPI operation ID.
        response_model_include: Fields to include in response model.
        response_model_exclude: Fields to exclude from response model.
        response_model_by_alias: Use field aliases in response.
        response_model_exclude_unset: Exclude unset fields from response.
        response_model_exclude_defaults: Exclude fields with default values.
        response_model_exclude_none: Exclude None values from response.
        include_in_schema: Include in OpenAPI schema.
        response_class: FastAPI response class to use.
        name: Display name for the route.
        route_class_override: Custom APIRoute class.
        callbacks: OpenAPI callbacks configuration.
        openapi_extra: Additional OpenAPI schema data.

    Returns:
        A decorator function that attaches the route configuration.
    """

    def wrapper(method: Callable[..., AnyT]) -> Callable[..., AnyT]:
        return Route(
            path=path,
            response_model=response_model,
            status_code=status_code,
            tags=tags,
            dependencies=dependencies,
            summary=summary,
            description=description,
            response_description=response_description,
            responses=responses,
            deprecated=deprecated,
            methods=methods,
            operation_id=operation_id,
            response_model_include=response_model_include,
            response_model_exclude=response_model_exclude,
            response_model_by_alias=response_model_by_alias,
            response_model_exclude_unset=response_model_exclude_unset,
            response_model_exclude_defaults=response_model_exclude_defaults,
            response_model_exclude_none=response_model_exclude_none,
            include_in_schema=include_in_schema,
            response_class=response_class,
            name=name,
            route_class_override=route_class_override,
            callbacks=callbacks,
            openapi_extra=openapi_extra,
        )(method)

    return wrapper

options: show_root_heading: false

`spakky.plugins.fastapi.routes.get` ¶

GET route decorator for FastAPI controllers.

Provides a convenience decorator for marking controller methods as HTTP GET endpoints with full FastAPI configuration support.

get(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) ¶

Decorator to mark a controller method as an HTTP GET endpoint.

Convenience wrapper around @route that automatically sets the HTTP method to GET. Supports all FastAPI route configuration options.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this route.	required
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.	`None`
`status_code`	`int \| None`	HTTP status code for successful responses.	`None`
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`
`summary`	`str \| None`	Short summary for OpenAPI documentation.	`None`
`description`	`str \| None`	Detailed description for OpenAPI documentation.	`None`
`response_description`	`str`	Description of successful response.	`'Successful Response'`
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.	`None`
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.	`None`
`operation_id`	`str \| None`	Custom OpenAPI operation ID.	`None`
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.	`None`
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.	`None`
`response_model_by_alias`	`bool`	Use field aliases in response.	`True`
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.	`False`
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.	`False`
`response_model_exclude_none`	`bool`	Exclude None values from response.	`False`
`include_in_schema`	`bool`	Include in OpenAPI schema.	`True`
`response_class`	`type[Response]`	FastAPI response class to use.	`JSONResponse`
`name`	`str \| None`	Display name for the route.	`None`
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.	`None`
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.	`None`
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that marks the method as a GET endpoint.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/get.py

def get(
    path: str,
    response_model: type[Any] | None = None,
    status_code: int | None = None,
    tags: list[str] | None = None,
    dependencies: Sequence[params.Depends] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    operation_id: str | None = None,
    response_model_include: SetIntStr | DictIntStrAny | None = None,
    response_model_exclude: SetIntStr | DictIntStrAny | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    include_in_schema: bool = True,
    response_class: type[Response] = JSONResponse,
    name: str | None = None,
    route_class_override: type[APIRoute] | None = None,
    callbacks: list[StarletteRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as an HTTP GET endpoint.

    Convenience wrapper around @route that automatically sets the HTTP method
    to GET. Supports all FastAPI route configuration options.

    Args:
        path: The URL path for this route.
        response_model: Pydantic model for response serialization.
        status_code: HTTP status code for successful responses.
        tags: OpenAPI tags for grouping endpoints.
        dependencies: FastAPI dependencies to inject.
        summary: Short summary for OpenAPI documentation.
        description: Detailed description for OpenAPI documentation.
        response_description: Description of successful response.
        responses: Additional response schemas for OpenAPI.
        deprecated: Whether this endpoint is deprecated.
        operation_id: Custom OpenAPI operation ID.
        response_model_include: Fields to include in response model.
        response_model_exclude: Fields to exclude from response model.
        response_model_by_alias: Use field aliases in response.
        response_model_exclude_unset: Exclude unset fields from response.
        response_model_exclude_defaults: Exclude fields with default values.
        response_model_exclude_none: Exclude None values from response.
        include_in_schema: Include in OpenAPI schema.
        response_class: FastAPI response class to use.
        name: Display name for the route.
        route_class_override: Custom APIRoute class.
        callbacks: OpenAPI callbacks configuration.
        openapi_extra: Additional OpenAPI schema data.

    Returns:
        A decorator function that marks the method as a GET endpoint.
    """
    return route(
        path=path,
        methods=[HTTPMethod.GET],
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        route_class_override=route_class_override,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
    )

options: show_root_heading: false

`spakky.plugins.fastapi.routes.post` ¶

POST route decorator for FastAPI controllers.

Provides a convenience decorator for marking controller methods as HTTP POST endpoints with full FastAPI configuration support.

post(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) ¶

Decorator to mark a controller method as an HTTP POST endpoint.

Convenience wrapper around @route that automatically sets the HTTP method to POST. Supports all FastAPI route configuration options.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this route.	required
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.	`None`
`status_code`	`int \| None`	HTTP status code for successful responses.	`None`
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`
`summary`	`str \| None`	Short summary for OpenAPI documentation.	`None`
`description`	`str \| None`	Detailed description for OpenAPI documentation.	`None`
`response_description`	`str`	Description of successful response.	`'Successful Response'`
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.	`None`
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.	`None`
`operation_id`	`str \| None`	Custom OpenAPI operation ID.	`None`
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.	`None`
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.	`None`
`response_model_by_alias`	`bool`	Use field aliases in response.	`True`
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.	`False`
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.	`False`
`response_model_exclude_none`	`bool`	Exclude None values from response.	`False`
`include_in_schema`	`bool`	Include in OpenAPI schema.	`True`
`response_class`	`type[Response]`	FastAPI response class to use.	`JSONResponse`
`name`	`str \| None`	Display name for the route.	`None`
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.	`None`
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.	`None`
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that marks the method as a POST endpoint.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/post.py

def post(
    path: str,
    response_model: type[Any] | None = None,
    status_code: int | None = None,
    tags: list[str] | None = None,
    dependencies: Sequence[params.Depends] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    operation_id: str | None = None,
    response_model_include: SetIntStr | DictIntStrAny | None = None,
    response_model_exclude: SetIntStr | DictIntStrAny | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    include_in_schema: bool = True,
    response_class: type[Response] = JSONResponse,
    name: str | None = None,
    route_class_override: type[APIRoute] | None = None,
    callbacks: list[StarletteRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as an HTTP POST endpoint.

    Convenience wrapper around @route that automatically sets the HTTP method
    to POST. Supports all FastAPI route configuration options.

    Args:
        path: The URL path for this route.
        response_model: Pydantic model for response serialization.
        status_code: HTTP status code for successful responses.
        tags: OpenAPI tags for grouping endpoints.
        dependencies: FastAPI dependencies to inject.
        summary: Short summary for OpenAPI documentation.
        description: Detailed description for OpenAPI documentation.
        response_description: Description of successful response.
        responses: Additional response schemas for OpenAPI.
        deprecated: Whether this endpoint is deprecated.
        operation_id: Custom OpenAPI operation ID.
        response_model_include: Fields to include in response model.
        response_model_exclude: Fields to exclude from response model.
        response_model_by_alias: Use field aliases in response.
        response_model_exclude_unset: Exclude unset fields from response.
        response_model_exclude_defaults: Exclude fields with default values.
        response_model_exclude_none: Exclude None values from response.
        include_in_schema: Include in OpenAPI schema.
        response_class: FastAPI response class to use.
        name: Display name for the route.
        route_class_override: Custom APIRoute class.
        callbacks: OpenAPI callbacks configuration.
        openapi_extra: Additional OpenAPI schema data.

    Returns:
        A decorator function that marks the method as a POST endpoint.
    """
    return route(
        path=path,
        methods=[HTTPMethod.POST],
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        route_class_override=route_class_override,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
    )

options: show_root_heading: false

`spakky.plugins.fastapi.routes.put` ¶

PUT route decorator for FastAPI controllers.

Provides a convenience decorator for marking controller methods as HTTP PUT endpoints with full FastAPI configuration support.

put(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) ¶

Decorator to mark a controller method as an HTTP PUT endpoint.

Convenience wrapper around @route that automatically sets the HTTP method to PUT. Supports all FastAPI route configuration options.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this route.	required
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.	`None`
`status_code`	`int \| None`	HTTP status code for successful responses.	`None`
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`
`summary`	`str \| None`	Short summary for OpenAPI documentation.	`None`
`description`	`str \| None`	Detailed description for OpenAPI documentation.	`None`
`response_description`	`str`	Description of successful response.	`'Successful Response'`
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.	`None`
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.	`None`
`operation_id`	`str \| None`	Custom OpenAPI operation ID.	`None`
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.	`None`
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.	`None`
`response_model_by_alias`	`bool`	Use field aliases in response.	`True`
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.	`False`
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.	`False`
`response_model_exclude_none`	`bool`	Exclude None values from response.	`False`
`include_in_schema`	`bool`	Include in OpenAPI schema.	`True`
`response_class`	`type[Response]`	FastAPI response class to use.	`JSONResponse`
`name`	`str \| None`	Display name for the route.	`None`
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.	`None`
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.	`None`
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that marks the method as a PUT endpoint.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/put.py

def put(
    path: str,
    response_model: type[Any] | None = None,
    status_code: int | None = None,
    tags: list[str] | None = None,
    dependencies: Sequence[params.Depends] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    operation_id: str | None = None,
    response_model_include: SetIntStr | DictIntStrAny | None = None,
    response_model_exclude: SetIntStr | DictIntStrAny | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    include_in_schema: bool = True,
    response_class: type[Response] = JSONResponse,
    name: str | None = None,
    route_class_override: type[APIRoute] | None = None,
    callbacks: list[StarletteRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as an HTTP PUT endpoint.

    Convenience wrapper around @route that automatically sets the HTTP method
    to PUT. Supports all FastAPI route configuration options.

    Args:
        path: The URL path for this route.
        response_model: Pydantic model for response serialization.
        status_code: HTTP status code for successful responses.
        tags: OpenAPI tags for grouping endpoints.
        dependencies: FastAPI dependencies to inject.
        summary: Short summary for OpenAPI documentation.
        description: Detailed description for OpenAPI documentation.
        response_description: Description of successful response.
        responses: Additional response schemas for OpenAPI.
        deprecated: Whether this endpoint is deprecated.
        operation_id: Custom OpenAPI operation ID.
        response_model_include: Fields to include in response model.
        response_model_exclude: Fields to exclude from response model.
        response_model_by_alias: Use field aliases in response.
        response_model_exclude_unset: Exclude unset fields from response.
        response_model_exclude_defaults: Exclude fields with default values.
        response_model_exclude_none: Exclude None values from response.
        include_in_schema: Include in OpenAPI schema.
        response_class: FastAPI response class to use.
        name: Display name for the route.
        route_class_override: Custom APIRoute class.
        callbacks: OpenAPI callbacks configuration.
        openapi_extra: Additional OpenAPI schema data.

    Returns:
        A decorator function that marks the method as a PUT endpoint.
    """
    return route(
        path=path,
        methods=[HTTPMethod.PUT],
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        route_class_override=route_class_override,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
    )

options: show_root_heading: false

`spakky.plugins.fastapi.routes.patch` ¶

PATCH route decorator for FastAPI controllers.

Provides a convenience decorator for marking controller methods as HTTP PATCH endpoints with full FastAPI configuration support.

patch(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) ¶

Decorator to mark a controller method as an HTTP PATCH endpoint.

Convenience wrapper around @route that automatically sets the HTTP method to PATCH. Supports all FastAPI route configuration options.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this route.	required
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.	`None`
`status_code`	`int \| None`	HTTP status code for successful responses.	`None`
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`
`summary`	`str \| None`	Short summary for OpenAPI documentation.	`None`
`description`	`str \| None`	Detailed description for OpenAPI documentation.	`None`
`response_description`	`str`	Description of successful response.	`'Successful Response'`
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.	`None`
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.	`None`
`operation_id`	`str \| None`	Custom OpenAPI operation ID.	`None`
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.	`None`
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.	`None`
`response_model_by_alias`	`bool`	Use field aliases in response.	`True`
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.	`False`
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.	`False`
`response_model_exclude_none`	`bool`	Exclude None values from response.	`False`
`include_in_schema`	`bool`	Include in OpenAPI schema.	`True`
`response_class`	`type[Response]`	FastAPI response class to use.	`JSONResponse`
`name`	`str \| None`	Display name for the route.	`None`
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.	`None`
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.	`None`
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that marks the method as a PATCH endpoint.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/patch.py

def patch(
    path: str,
    response_model: type[Any] | None = None,
    status_code: int | None = None,
    tags: list[str] | None = None,
    dependencies: Sequence[params.Depends] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    operation_id: str | None = None,
    response_model_include: SetIntStr | DictIntStrAny | None = None,
    response_model_exclude: SetIntStr | DictIntStrAny | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    include_in_schema: bool = True,
    response_class: type[Response] = JSONResponse,
    name: str | None = None,
    route_class_override: type[APIRoute] | None = None,
    callbacks: list[StarletteRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as an HTTP PATCH endpoint.

    Convenience wrapper around @route that automatically sets the HTTP method
    to PATCH. Supports all FastAPI route configuration options.

    Args:
        path: The URL path for this route.
        response_model: Pydantic model for response serialization.
        status_code: HTTP status code for successful responses.
        tags: OpenAPI tags for grouping endpoints.
        dependencies: FastAPI dependencies to inject.
        summary: Short summary for OpenAPI documentation.
        description: Detailed description for OpenAPI documentation.
        response_description: Description of successful response.
        responses: Additional response schemas for OpenAPI.
        deprecated: Whether this endpoint is deprecated.
        operation_id: Custom OpenAPI operation ID.
        response_model_include: Fields to include in response model.
        response_model_exclude: Fields to exclude from response model.
        response_model_by_alias: Use field aliases in response.
        response_model_exclude_unset: Exclude unset fields from response.
        response_model_exclude_defaults: Exclude fields with default values.
        response_model_exclude_none: Exclude None values from response.
        include_in_schema: Include in OpenAPI schema.
        response_class: FastAPI response class to use.
        name: Display name for the route.
        route_class_override: Custom APIRoute class.
        callbacks: OpenAPI callbacks configuration.
        openapi_extra: Additional OpenAPI schema data.

    Returns:
        A decorator function that marks the method as a PATCH endpoint.
    """
    return route(
        path=path,
        methods=[HTTPMethod.PATCH],
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        route_class_override=route_class_override,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
    )

options: show_root_heading: false

`spakky.plugins.fastapi.routes.delete` ¶

DELETE route decorator for FastAPI controllers.

Provides a convenience decorator for marking controller methods as HTTP DELETE endpoints with full FastAPI configuration support.

delete(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) ¶

Decorator to mark a controller method as an HTTP DELETE endpoint.

Convenience wrapper around @route that automatically sets the HTTP method to DELETE. Supports all FastAPI route configuration options.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this route.	required
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.	`None`
`status_code`	`int \| None`	HTTP status code for successful responses.	`None`
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`
`summary`	`str \| None`	Short summary for OpenAPI documentation.	`None`
`description`	`str \| None`	Detailed description for OpenAPI documentation.	`None`
`response_description`	`str`	Description of successful response.	`'Successful Response'`
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.	`None`
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.	`None`
`operation_id`	`str \| None`	Custom OpenAPI operation ID.	`None`
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.	`None`
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.	`None`
`response_model_by_alias`	`bool`	Use field aliases in response.	`True`
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.	`False`
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.	`False`
`response_model_exclude_none`	`bool`	Exclude None values from response.	`False`
`include_in_schema`	`bool`	Include in OpenAPI schema.	`True`
`response_class`	`type[Response]`	FastAPI response class to use.	`JSONResponse`
`name`	`str \| None`	Display name for the route.	`None`
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.	`None`
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.	`None`
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that marks the method as a DELETE endpoint.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/delete.py

def delete(
    path: str,
    response_model: type[Any] | None = None,
    status_code: int | None = None,
    tags: list[str] | None = None,
    dependencies: Sequence[params.Depends] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    operation_id: str | None = None,
    response_model_include: SetIntStr | DictIntStrAny | None = None,
    response_model_exclude: SetIntStr | DictIntStrAny | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    include_in_schema: bool = True,
    response_class: type[Response] = JSONResponse,
    name: str | None = None,
    route_class_override: type[APIRoute] | None = None,
    callbacks: list[StarletteRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as an HTTP DELETE endpoint.

    Convenience wrapper around @route that automatically sets the HTTP method
    to DELETE. Supports all FastAPI route configuration options.

    Args:
        path: The URL path for this route.
        response_model: Pydantic model for response serialization.
        status_code: HTTP status code for successful responses.
        tags: OpenAPI tags for grouping endpoints.
        dependencies: FastAPI dependencies to inject.
        summary: Short summary for OpenAPI documentation.
        description: Detailed description for OpenAPI documentation.
        response_description: Description of successful response.
        responses: Additional response schemas for OpenAPI.
        deprecated: Whether this endpoint is deprecated.
        operation_id: Custom OpenAPI operation ID.
        response_model_include: Fields to include in response model.
        response_model_exclude: Fields to exclude from response model.
        response_model_by_alias: Use field aliases in response.
        response_model_exclude_unset: Exclude unset fields from response.
        response_model_exclude_defaults: Exclude fields with default values.
        response_model_exclude_none: Exclude None values from response.
        include_in_schema: Include in OpenAPI schema.
        response_class: FastAPI response class to use.
        name: Display name for the route.
        route_class_override: Custom APIRoute class.
        callbacks: OpenAPI callbacks configuration.
        openapi_extra: Additional OpenAPI schema data.

    Returns:
        A decorator function that marks the method as a DELETE endpoint.
    """
    return route(
        path=path,
        methods=[HTTPMethod.DELETE],
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        route_class_override=route_class_override,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
    )

options: show_root_heading: false

`spakky.plugins.fastapi.routes.head` ¶

HEAD route decorator for FastAPI controllers.

Provides a convenience decorator for marking controller methods as HTTP HEAD endpoints with full FastAPI configuration support.

head(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) ¶

Decorator to mark a controller method as an HTTP HEAD endpoint.

Convenience wrapper around @route that automatically sets the HTTP method to HEAD. Supports all FastAPI route configuration options.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this route.	required
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.	`None`
`status_code`	`int \| None`	HTTP status code for successful responses.	`None`
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`
`summary`	`str \| None`	Short summary for OpenAPI documentation.	`None`
`description`	`str \| None`	Detailed description for OpenAPI documentation.	`None`
`response_description`	`str`	Description of successful response.	`'Successful Response'`
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.	`None`
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.	`None`
`operation_id`	`str \| None`	Custom OpenAPI operation ID.	`None`
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.	`None`
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.	`None`
`response_model_by_alias`	`bool`	Use field aliases in response.	`True`
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.	`False`
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.	`False`
`response_model_exclude_none`	`bool`	Exclude None values from response.	`False`
`include_in_schema`	`bool`	Include in OpenAPI schema.	`True`
`response_class`	`type[Response]`	FastAPI response class to use.	`JSONResponse`
`name`	`str \| None`	Display name for the route.	`None`
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.	`None`
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.	`None`
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that marks the method as a HEAD endpoint.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/head.py

def head(
    path: str,
    response_model: type[Any] | None = None,
    status_code: int | None = None,
    tags: list[str] | None = None,
    dependencies: Sequence[params.Depends] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    operation_id: str | None = None,
    response_model_include: SetIntStr | DictIntStrAny | None = None,
    response_model_exclude: SetIntStr | DictIntStrAny | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    include_in_schema: bool = True,
    response_class: type[Response] = JSONResponse,
    name: str | None = None,
    route_class_override: type[APIRoute] | None = None,
    callbacks: list[StarletteRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as an HTTP HEAD endpoint.

    Convenience wrapper around @route that automatically sets the HTTP method
    to HEAD. Supports all FastAPI route configuration options.

    Args:
        path: The URL path for this route.
        response_model: Pydantic model for response serialization.
        status_code: HTTP status code for successful responses.
        tags: OpenAPI tags for grouping endpoints.
        dependencies: FastAPI dependencies to inject.
        summary: Short summary for OpenAPI documentation.
        description: Detailed description for OpenAPI documentation.
        response_description: Description of successful response.
        responses: Additional response schemas for OpenAPI.
        deprecated: Whether this endpoint is deprecated.
        operation_id: Custom OpenAPI operation ID.
        response_model_include: Fields to include in response model.
        response_model_exclude: Fields to exclude from response model.
        response_model_by_alias: Use field aliases in response.
        response_model_exclude_unset: Exclude unset fields from response.
        response_model_exclude_defaults: Exclude fields with default values.
        response_model_exclude_none: Exclude None values from response.
        include_in_schema: Include in OpenAPI schema.
        response_class: FastAPI response class to use.
        name: Display name for the route.
        route_class_override: Custom APIRoute class.
        callbacks: OpenAPI callbacks configuration.
        openapi_extra: Additional OpenAPI schema data.

    Returns:
        A decorator function that marks the method as a HEAD endpoint.
    """
    return route(
        path=path,
        methods=[HTTPMethod.HEAD],
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        route_class_override=route_class_override,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
    )

options: show_root_heading: false

`spakky.plugins.fastapi.routes.options` ¶

OPTIONS route decorator for FastAPI controllers.

Provides a convenience decorator for marking controller methods as HTTP OPTIONS endpoints with full FastAPI configuration support.

options(path, response_model=None, status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description='Successful Response', responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=JSONResponse, name=None, route_class_override=None, callbacks=None, openapi_extra=None) ¶

Decorator to mark a controller method as an HTTP OPTIONS endpoint.

Convenience wrapper around @route that automatically sets the HTTP method to OPTIONS. Supports all FastAPI route configuration options.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this route.	required
`response_model`	`type[Any] \| None`	Pydantic model for response serialization.	`None`
`status_code`	`int \| None`	HTTP status code for successful responses.	`None`
`tags`	`list[str] \| None`	OpenAPI tags for grouping endpoints.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`
`summary`	`str \| None`	Short summary for OpenAPI documentation.	`None`
`description`	`str \| None`	Detailed description for OpenAPI documentation.	`None`
`response_description`	`str`	Description of successful response.	`'Successful Response'`
`responses`	`dict[int \| str, dict[str, Any]] \| None`	Additional response schemas for OpenAPI.	`None`
`deprecated`	`bool \| None`	Whether this endpoint is deprecated.	`None`
`operation_id`	`str \| None`	Custom OpenAPI operation ID.	`None`
`response_model_include`	`SetIntStr \| DictIntStrAny \| None`	Fields to include in response model.	`None`
`response_model_exclude`	`SetIntStr \| DictIntStrAny \| None`	Fields to exclude from response model.	`None`
`response_model_by_alias`	`bool`	Use field aliases in response.	`True`
`response_model_exclude_unset`	`bool`	Exclude unset fields from response.	`False`
`response_model_exclude_defaults`	`bool`	Exclude fields with default values.	`False`
`response_model_exclude_none`	`bool`	Exclude None values from response.	`False`
`include_in_schema`	`bool`	Include in OpenAPI schema.	`True`
`response_class`	`type[Response]`	FastAPI response class to use.	`JSONResponse`
`name`	`str \| None`	Display name for the route.	`None`
`route_class_override`	`type[APIRoute] \| None`	Custom APIRoute class.	`None`
`callbacks`	`list[Route] \| None`	OpenAPI callbacks configuration.	`None`
`openapi_extra`	`dict[str, Any] \| None`	Additional OpenAPI schema data.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that marks the method as an OPTIONS endpoint.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/options.py

def options(
    path: str,
    response_model: type[Any] | None = None,
    status_code: int | None = None,
    tags: list[str] | None = None,
    dependencies: Sequence[params.Depends] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    operation_id: str | None = None,
    response_model_include: SetIntStr | DictIntStrAny | None = None,
    response_model_exclude: SetIntStr | DictIntStrAny | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    include_in_schema: bool = True,
    response_class: type[Response] = JSONResponse,
    name: str | None = None,
    route_class_override: type[APIRoute] | None = None,
    callbacks: list[StarletteRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as an HTTP OPTIONS endpoint.

    Convenience wrapper around @route that automatically sets the HTTP method
    to OPTIONS. Supports all FastAPI route configuration options.

    Args:
        path: The URL path for this route.
        response_model: Pydantic model for response serialization.
        status_code: HTTP status code for successful responses.
        tags: OpenAPI tags for grouping endpoints.
        dependencies: FastAPI dependencies to inject.
        summary: Short summary for OpenAPI documentation.
        description: Detailed description for OpenAPI documentation.
        response_description: Description of successful response.
        responses: Additional response schemas for OpenAPI.
        deprecated: Whether this endpoint is deprecated.
        operation_id: Custom OpenAPI operation ID.
        response_model_include: Fields to include in response model.
        response_model_exclude: Fields to exclude from response model.
        response_model_by_alias: Use field aliases in response.
        response_model_exclude_unset: Exclude unset fields from response.
        response_model_exclude_defaults: Exclude fields with default values.
        response_model_exclude_none: Exclude None values from response.
        include_in_schema: Include in OpenAPI schema.
        response_class: FastAPI response class to use.
        name: Display name for the route.
        route_class_override: Custom APIRoute class.
        callbacks: OpenAPI callbacks configuration.
        openapi_extra: Additional OpenAPI schema data.

    Returns:
        A decorator function that marks the method as an OPTIONS endpoint.
    """
    return route(
        path=path,
        methods=[HTTPMethod.OPTIONS],
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        route_class_override=route_class_override,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
    )

options: show_root_heading: false

`spakky.plugins.fastapi.routes.websocket` ¶

WebSocket route decorator for FastAPI controllers.

Provides a decorator for marking controller methods as WebSocket endpoints with support for FastAPI WebSocket configuration.

`WebSocketRoute(path, name=None, dependencies=None)` `dataclass` ¶

Bases: FunctionAnnotation

Function annotation for marking methods as WebSocket endpoints.

Stores WebSocket route configuration including path and dependencies.

Attributes:

Name	Type	Description
`path`	`str`	The URL path for this WebSocket endpoint.
`name`	`str \| None`	Display name for the WebSocket route.
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.

`websocket(path, name=None, dependencies=None)` ¶

Decorator to mark a controller method as a WebSocket endpoint.

Attaches WebSocket route configuration to the method which will be registered by the RegisterRoutesPostProcessor during container initialization.

Parameters:

Name	Type	Description	Default
`path`	`str`	The URL path for this WebSocket endpoint.	required
`name`	`str \| None`	Display name for the WebSocket route.	`None`
`dependencies`	`Sequence[Depends] \| None`	FastAPI dependencies to inject.	`None`

Returns:

Type	Description
`Callable[[Callable[..., AnyT]], Callable[..., AnyT]]`	A decorator function that attaches the WebSocket route configuration.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/routes/websocket.py

def websocket(
    path: str,
    name: str | None = None,
    dependencies: Sequence[params.Depends] | None = None,
) -> Callable[[Callable[..., AnyT]], Callable[..., AnyT]]:
    """Decorator to mark a controller method as a WebSocket endpoint.

    Attaches WebSocket route configuration to the method which will be
    registered by the RegisterRoutesPostProcessor during container initialization.

    Args:
        path: The URL path for this WebSocket endpoint.
        name: Display name for the WebSocket route.
        dependencies: FastAPI dependencies to inject.

    Returns:
        A decorator function that attaches the WebSocket route configuration.
    """
    return WebSocketRoute(
        path=path,
        name=name,
        dependencies=dependencies,
    )

options: show_root_heading: false

미들웨어¶

`spakky.plugins.fastapi.middlewares.error_handling` ¶

Error handling middleware for FastAPI applications.

Provides global exception handling that converts Spakky FastAPI errors to appropriate JSON responses and handles unexpected exceptions gracefully.

`ErrorHandlingMiddleware(app, dispatch=None, debug=False)` ¶

Bases: BaseHTTPMiddleware

Middleware that catches and converts exceptions to JSON responses.

Handles both Spakky FastAPI errors and unexpected exceptions, converting them to appropriate JSON responses with correct HTTP status codes.

Initialize the error handling middleware.

Parameters:

Name	Type	Description	Default
`app`	`ASGIApp`	The ASGI application.	required
`dispatch`	`DispatchFunction \| None`	Optional custom dispatch function.	`None`
`debug`	`bool`	Whether to include tracebacks in error responses.	`False`

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/middlewares/error_handling.py

def __init__(
    self,
    app: ASGIApp,
    dispatch: DispatchFunction | None = None,
    debug: bool = False,
) -> None:
    """Initialize the error handling middleware.

    Args:
        app: The ASGI application.
        dispatch: Optional custom dispatch function.
        debug: Whether to include tracebacks in error responses.
    """
    super().__init__(app, dispatch)
    self.__debug = debug

`dispatch(request, call_next)` `async` ¶

Process the request with error handling.

Catches exceptions during request processing and converts them to appropriate JSON responses. Spakky FastAPI errors are converted using their to_response() method, while unexpected exceptions return 500.

Parameters:

Name	Type	Description	Default
`request`	`Request`	The incoming HTTP request.	required
`call_next`	`Next`	Function to call the next middleware or route handler.	required

Returns:

Type	Description
`Response`	The HTTP response, either from successful processing or error handling.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/middlewares/error_handling.py

async def dispatch(self, request: Request, call_next: Next) -> Response:
    """Process the request with error handling.

    Catches exceptions during request processing and converts them to
    appropriate JSON responses. Spakky FastAPI errors are converted using
    their to_response() method, while unexpected exceptions return 500.

    Args:
        request: The incoming HTTP request.
        call_next: Function to call the next middleware or route handler.

    Returns:
        The HTTP response, either from successful processing or error handling.
    """
    try:
        return await call_next(request)
    except AbstractSpakkyFastAPIError as e:
        return e.to_response()
    except Exception as e:
        logger.exception(f"Unhandled exception during request processing: {e!r}")
        return InternalServerError().to_response(self.__debug)

options: show_root_heading: false

`spakky.plugins.fastapi.middlewares.tracing` ¶

Tracing middleware for W3C Trace Context propagation.

Extracts trace context from incoming HTTP request headers, activates a child span for the request lifetime, and injects trace context into response headers.

`TracingMiddleware(app, dispatch=None, *, propagator)` ¶

Bases: BaseHTTPMiddleware

Middleware that propagates W3C Trace Context across HTTP boundaries.

Extracts traceparent from request headers, activates a child span for the request lifetime, and injects traceparent into response headers. When no incoming trace context is present, a new root trace is started.

Initialize the tracing middleware.

Parameters:

Name	Type	Description	Default
`app`	`ASGIApp`	The ASGI application.	required
`dispatch`	`DispatchFunction \| None`	Optional custom dispatch function.	`None`
`propagator`	`ITracePropagator`	Trace context propagator for extract/inject.	required

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/middlewares/tracing.py

def __init__(
    self,
    app: ASGIApp,
    dispatch: DispatchFunction | None = None,
    *,
    propagator: ITracePropagator,
) -> None:
    """Initialize the tracing middleware.

    Args:
        app: The ASGI application.
        dispatch: Optional custom dispatch function.
        propagator: Trace context propagator for extract/inject.
    """
    super().__init__(app, dispatch)
    self.__propagator = propagator

`dispatch(request, call_next)` `async` ¶

Extract trace context, process request, and inject into response.

Parameters:

Name	Type	Description	Default
`request`	`Request`	The incoming HTTP request.	required
`call_next`	`Next`	Function to call the next middleware or route handler.	required

Returns:

Type	Description
`Response`	The HTTP response with trace context headers injected.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/middlewares/tracing.py

async def dispatch(self, request: Request, call_next: Next) -> Response:
    """Extract trace context, process request, and inject into response.

    Args:
        request: The incoming HTTP request.
        call_next: Function to call the next middleware or route handler.

    Returns:
        The HTTP response with trace context headers injected.
    """
    carrier: dict[str, str] = dict(request.headers)
    parent = self.__propagator.extract(carrier)
    ctx = parent.child() if parent is not None else TraceContext.new_root()
    TraceContext.set(ctx)
    try:
        response = await call_next(request)
        response_carrier: dict[str, str] = {}
        self.__propagator.inject(response_carrier)
        for key, value in response_carrier.items():
            response.headers[key] = value
        return response
    finally:
        TraceContext.clear()

options: show_root_heading: false

후처리기s¶

`spakky.plugins.fastapi.post_processors.bind_lifespan` ¶

Post-processor for binding FastAPI lifespan to ApplicationContext lifecycle.

Automatically wraps FastAPI lifespan to ensure ApplicationContext.stop() is called when FastAPI shuts down, enabling graceful shutdown of background services like RabbitMQ consumers.

`BindLifespanPostProcessor` ¶

Bases: IPostProcessor, IApplicationContextAware

Post-processor that binds FastAPI lifespan to ApplicationContext lifecycle.

Wraps the FastAPI lifespan handler to ensure ApplicationContext.stop() is called when FastAPI shuts down. This enables graceful shutdown of all background services registered with the application context.

User-defined lifespan handlers are preserved and executed normally.

`set_application_context(application_context)` ¶

Set the application context for lifecycle binding.

Parameters:

Name	Type	Description	Default
`application_context`	`IApplicationContext`	The application context to stop on shutdown.	required

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/bind_lifespan.py

@override
def set_application_context(self, application_context: IApplicationContext) -> None:
    """Set the application context for lifecycle binding.

    Args:
        application_context: The application context to stop on shutdown.
    """
    self.__application_context = application_context

`post_process(pod)` ¶

Wrap FastAPI lifespan to bind ApplicationContext lifecycle.

Parameters:

Name	Type	Description	Default
`pod`	`object`	The Pod to process.	required

Returns:

Type	Description
`object`	The Pod with lifespan wrapped if it's a FastAPI instance.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/bind_lifespan.py

@override
def post_process(self, pod: object) -> object:
    """Wrap FastAPI lifespan to bind ApplicationContext lifecycle.

    Args:
        pod: The Pod to process.

    Returns:
        The Pod with lifespan wrapped if it's a FastAPI instance.
    """
    if not isinstance(pod, FastAPI):
        return pod

    original_lifespan = pod.router.lifespan_context
    application_context = self.__application_context

    @asynccontextmanager
    async def wrapped_lifespan(
        app: FastAPI,
    ) -> AsyncGenerator[Mapping[str, Any], None]:
        try:
            async with original_lifespan(app) as state:
                yield state if state is not None else {}
        finally:
            application_context.stop()

    pod.router.lifespan_context = wrapped_lifespan
    return pod

options: show_root_heading: false

`spakky.plugins.fastapi.post_processors.add_builtin_middlewares` ¶

Post-processor for adding built-in middleware to FastAPI applications.

Automatically injects error handling and context management middleware into FastAPI instances registered in the container. When the tracing plugin is loaded, tracing middleware is also added.

`AddBuiltInMiddlewaresPostProcessor` ¶

Bases: IPostProcessor, IApplicationContextAware

Post-processor that adds built-in middleware to FastAPI instances.

Injects error handling and tracing middleware into any FastAPI instance created as a Pod. Tracing middleware is only added when the tracing plugin is loaded. Runs early in the post-processor chain (Order 0).

`set_application_context(application_context)` ¶

Set the application context for middleware injection.

Parameters:

Name	Type	Description	Default
`application_context`	`IApplicationContext`	The application context to use for middleware.	required

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/add_builtin_middlewares.py

@override
def set_application_context(self, application_context: IApplicationContext) -> None:
    """Set the application context for middleware injection.

    Args:
        application_context: The application context to use for middleware.
    """
    self.__application_context = application_context

`post_process(pod)` ¶

Add built-in middleware to FastAPI instances.

If the Pod is a FastAPI instance, adds error handling middleware and optionally tracing middleware. Non-FastAPI Pods are returned unchanged.

Middleware execution order (outermost first): 1. TracingMiddleware — extract/inject W3C Trace Context 2. ErrorHandlingMiddleware — catch exceptions → JSON responses

add_middleware prepends, so the last added middleware executes first.

Parameters:

Name	Type	Description	Default
`pod`	`object`	The Pod to process.	required

Returns:

Type	Description
`object`	The Pod, potentially with middleware added if it's a FastAPI instance.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/add_builtin_middlewares.py

@override
def post_process(self, pod: object) -> object:
    """Add built-in middleware to FastAPI instances.

    If the Pod is a FastAPI instance, adds error handling middleware and
    optionally tracing middleware.  Non-FastAPI Pods are returned unchanged.

    Middleware execution order (outermost first):
    1. ``TracingMiddleware`` — extract/inject W3C Trace Context
    2. ``ErrorHandlingMiddleware`` — catch exceptions → JSON responses

    ``add_middleware`` prepends, so the last added middleware executes first.

    Args:
        pod: The Pod to process.

    Returns:
        The Pod, potentially with middleware added if it's a FastAPI instance.
    """
    if not isinstance(pod, FastAPI):
        return pod

    pod.add_middleware(
        ErrorHandlingMiddleware,
        debug=pod.debug,
    )

    propagator = self.__application_context.get_or_none(ITracePropagator)
    if propagator is not None:
        pod.add_middleware(
            TracingMiddleware,
            propagator=propagator,
        )

    return pod

options: show_root_heading: false

`spakky.plugins.fastapi.post_processors.register_routes` ¶

Post-processor for registering API controller routes.

Automatically discovers and registers routes from @ApiController decorated classes, creating FastAPI endpoints with proper dependency injection.

`RegisterRoutesPostProcessor` ¶

Bases: IPostProcessor, IContainerAware, IApplicationContextAware

Post-processor that registers routes from API controllers.

Scans @ApiController decorated classes for @route decorated methods and automatically registers them as FastAPI endpoints with proper dependency injection and response model inference.

`set_container(container)` ¶

Set the container for dependency injection.

Parameters:

Name	Type	Description	Default
`container`	`IContainer`	The IoC container.	required

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/register_routes.py

@override
def set_container(self, container: IContainer) -> None:
    """Set the container for dependency injection.

    Args:
        container: The IoC container.
    """
    self.__container = container

`set_application_context(application_context)` ¶

Set the application context.

Parameters:

Name	Type	Description	Default
`application_context`	`IApplicationContext`	The application context.	required

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/register_routes.py

@override
def set_application_context(self, application_context: IApplicationContext) -> None:
    """Set the application context.

    Args:
        application_context: The application context.
    """
    self.__application_context = application_context

`post_process(pod)` ¶

Register routes from API controllers.

Scans the controller for methods decorated with @route or @websocket and registers them as FastAPI endpoints. Automatically infers response models from return type annotations and sets up dependency injection.

Parameters:

Name	Type	Description	Default
`pod`	`object`	The Pod to process, potentially an API controller.	required

Returns:

Type	Description
`object`	The Pod, with routes registered if it's an API controller.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/register_routes.py

@override
def post_process(self, pod: object) -> object:
    """Register routes from API controllers.

    Scans the controller for methods decorated with @route or @websocket
    and registers them as FastAPI endpoints. Automatically infers response
    models from return type annotations and sets up dependency injection.

    Args:
        pod: The Pod to process, potentially an API controller.

    Returns:
        The Pod, with routes registered if it's an API controller.
    """
    if not ApiController.exists(pod):
        return pod

    fast_api = self.__container.get(FastAPI)
    controller = ApiController.get(pod)
    router: APIRouter = APIRouter(prefix=controller.prefix, tags=controller.tags)
    for name, method in getmembers(pod, callable):
        route: Route | None = Route.get_or_none(method)
        websocket_route: WebSocketRoute | None = WebSocketRoute.get_or_none(method)
        if route is None and websocket_route is None:
            continue

        if route is not None:
            # pylint: disable=line-too-long
            logger.debug(
                f"{route.methods!r} {controller.prefix}{route.path} -> {method.__qualname__}"
            )
            if route.name is None:
                route.name = " ".join([x.capitalize() for x in name.split("_")])
            if route.description is None:
                route.description = method.__doc__
            if route.response_model is None:
                return_annotation: type | None = signature(method).return_annotation
                if return_annotation is not None:
                    try:
                        create_model_field("", return_annotation)
                        route.response_model = return_annotation
                    except FastAPIError as e:
                        logger.debug(
                            f"Failed to infer response model for {method.__qualname__}: {type(e).__name__}"
                        )

            @wraps(method)
            async def endpoint(
                *args: Any,
                method_name: str = name,
                controller_type: type[object] = controller.type_,
                context: IContainer = self.__container,
                **kwargs: Any,
            ) -> Any:
                # Reset context so request-scoped Pods do not leak between
                # consecutive FastAPI requests processed on the same worker.
                self.__application_context.clear_context()
                controller_instance = context.get(controller_type)
                method_to_call = getattr(  # route decorator method lookup
                    controller_instance, method_name
                )  # 프레임워크 내부: 컨트롤러 메서드 동적 디스패치
                return await method_to_call(*args, **kwargs)

            router.add_api_route(endpoint=endpoint, **asdict(route))
        if websocket_route is not None:
            # pylint: disable=line-too-long
            logger.debug(
                f"[WebSocket] {controller.prefix}{websocket_route.path} -> {method.__qualname__}"
            )
            if websocket_route.name is None:
                websocket_route.name = " ".join(
                    [x.capitalize() for x in name.split("_")]
                )

            @wraps(method)
            async def websocket_endpoint(
                *args: Any,
                method_name: str = name,
                controller_type: type[object] = controller.type_,
                context: IContainer = self.__container,
                **kwargs: Any,
            ) -> Any:
                # WebSocket sessions reuse the same event loop task, so we
                # clear the context to guarantee per-connection isolation.
                self.__application_context.clear_context()
                controller_instance = context.get(controller_type)
                method_to_call = getattr(  # websocket decorator method lookup
                    controller_instance, method_name
                )  # 프레임워크 내부: 컨트롤러 메서드 동적 디스패치
                return await method_to_call(*args, **kwargs)

            router.add_api_websocket_route(
                endpoint=websocket_endpoint, **asdict(websocket_route)
            )
    fast_api.include_router(router)
    return pod

options: show_root_heading: false

`spakky.plugins.fastapi.post_processors.register_actuator` ¶

Post-processor for registering actuator HTTP endpoints.

`RegisterActuatorPostProcessor` ¶

Bases: IPostProcessor, IContainerAware

Register actuator endpoints when the actuator service is available.

`set_container(container)` ¶

Set the container used to resolve actuator dependencies.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/register_actuator.py

@override
def set_container(self, container: IContainer) -> None:
    """Set the container used to resolve actuator dependencies."""
    self.__container = container

`post_process(pod)` ¶

Register actuator routes on FastAPI instances.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/post_processors/register_actuator.py

@override
def post_process(self, pod: object) -> object:
    """Register actuator routes on FastAPI instances."""
    if not isinstance(pod, FastAPI):
        return pod

    service = self.__container.get_or_none(ActuatorAggregationService)
    if service is None:
        return pod

    config = self.__container.get_or_none(FastAPIActuatorConfig)
    if config is None:
        config = FastAPIActuatorConfig()
    if not config.enabled:
        return pod

    self._register_routes(pod, service, config)
    return pod

options: show_root_heading: false

Actuator¶

`spakky.plugins.fastapi.actuator` ¶

FastAPI configuration for actuator HTTP endpoints.

`FastAPIActuatorConfig(*, enabled=True, base_path='/actuator', health_enabled=True, readiness_enabled=True, liveness_enabled=True, info_enabled=True)` ¶

Configuration for FastAPI actuator endpoint exposure.

Initialize actuator endpoint exposure configuration.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/actuator.py

def __init__(
    self,
    *,
    enabled: bool = True,
    base_path: str = "/actuator",
    health_enabled: bool = True,
    readiness_enabled: bool = True,
    liveness_enabled: bool = True,
    info_enabled: bool = True,
) -> None:
    """Initialize actuator endpoint exposure configuration."""
    self.enabled = enabled
    self.base_path = self._normalize_base_path(base_path)
    self.health_enabled = health_enabled
    self.readiness_enabled = readiness_enabled
    self.liveness_enabled = liveness_enabled
    self.info_enabled = info_enabled

options: show_root_heading: false

에러¶

`spakky.plugins.fastapi.error` ¶

HTTP error classes for FastAPI integration.

Provides base error classes and common HTTP error responses that integrate with FastAPI's error handling system. All errors can be converted to JSON responses with appropriate HTTP status codes.

`AbstractSpakkyFastAPIError` ¶

Bases: AbstractSpakkyFrameworkError, ABC

Base error class for FastAPI-related exceptions.

Provides automatic conversion to FastAPI JSON responses with appropriate HTTP status codes. Subclasses should define a status_code class variable.

Attributes:

Name	Type	Description
`status_code`	`int`	HTTP status code for this error type.
`message`	`str`	Human-readable error message.

`status_code` `class-attribute` ¶

HTTP status code returned for this error type.

`to_response(show_traceback=False)` ¶

Convert the error to a FastAPI JSON response.

Parameters:

Name	Type	Description	Default
`show_traceback`	`bool`	Whether to include the full traceback in the response.	`False`

Returns:

Type	Description
`JSONResponse`	A JSON response containing the error message, args, and optional traceback.

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/error.py

def to_response(self, show_traceback: bool = False) -> JSONResponse:
    """Convert the error to a FastAPI JSON response.

    Args:
        show_traceback: Whether to include the full traceback in the response.

    Returns:
        A JSON response containing the error message, args, and optional traceback.
    """
    return JSONResponse(
        content={
            "message": self.message,
            "args": [str(x) for x in self.args],
            "traceback": traceback.format_exc() if show_traceback else None,
        },
        status_code=self.status_code,
    )

`BadRequest` ¶

Bases: AbstractSpakkyFastAPIError

HTTP 400 Bad Request error.

`Unauthorized` ¶

Bases: AbstractSpakkyFastAPIError

HTTP 401 Unauthorized error.

`Forbidden` ¶

Bases: AbstractSpakkyFastAPIError

HTTP 403 Forbidden error.

`NotFound` ¶

Bases: AbstractSpakkyFastAPIError

HTTP 404 Not Found error.

`Conflict` ¶

Bases: AbstractSpakkyFastAPIError

HTTP 409 Conflict error.

`InternalServerError` ¶

Bases: AbstractSpakkyFastAPIError

HTTP 500 Internal Server Error.

options: show_root_heading: false

플러그인 진입점¶

`spakky.plugins.fastapi.main` ¶

Plugin initialization for FastAPI integration.

Registers post-processors that enable automatic route registration and built-in middleware injection for FastAPI applications.

`initialize(app)` ¶

Initialize the FastAPI plugin.

Registers post-processors for automatic route registration and middleware injection. This function is called automatically by the Spakky framework during plugin loading.

Parameters:

Name	Type	Description	Default
`app`	`SpakkyApplication`	The Spakky application instance.	required

Source code in plugins/spakky-fastapi/src/spakky/plugins/fastapi/main.py

def initialize(app: SpakkyApplication) -> None:
    """Initialize the FastAPI plugin.

    Registers post-processors for automatic route registration and middleware
    injection. This function is called automatically by the Spakky framework
    during plugin loading.

    Args:
        app: The Spakky application instance.
    """
    app.add(BindLifespanPostProcessor)
    app.add(AddBuiltInMiddlewaresPostProcessor)
    app.add(RegisterActuatorPostProcessor)
    app.add(RegisterRoutesPostProcessor)

options: show_root_heading: false

spakky-fastapi¶

스테레오타입¶

spakky.plugins.fastapi.stereotypes.api_controller ¶

ApiController(prefix, tags=None, *, name='', scope=Scope.SINGLETON) dataclass ¶

prefix instance-attribute ¶

tags = None class-attribute instance-attribute ¶

라우트¶

spakky.plugins.fastapi.routes.route ¶

HTTPMethod ¶

__repr__() ¶

spakky.plugins.fastapi.routes.get ¶

spakky.plugins.fastapi.routes.post ¶

spakky.plugins.fastapi.routes.put ¶

spakky.plugins.fastapi.routes.patch ¶

spakky.plugins.fastapi.routes.delete ¶

spakky.plugins.fastapi.routes.head ¶

spakky.plugins.fastapi.routes.options ¶

spakky.plugins.fastapi.routes.websocket ¶

WebSocketRoute(path, name=None, dependencies=None) dataclass ¶

websocket(path, name=None, dependencies=None) ¶

미들웨어¶

spakky.plugins.fastapi.middlewares.error_handling ¶

ErrorHandlingMiddleware(app, dispatch=None, debug=False) ¶

dispatch(request, call_next) async ¶

spakky.plugins.fastapi.middlewares.tracing ¶

TracingMiddleware(app, dispatch=None, *, propagator) ¶

dispatch(request, call_next) async ¶

후처리기s¶

spakky.plugins.fastapi.post_processors.bind_lifespan ¶

BindLifespanPostProcessor ¶

set_application_context(application_context) ¶

post_process(pod) ¶

spakky.plugins.fastapi.post_processors.add_builtin_middlewares ¶

AddBuiltInMiddlewaresPostProcessor ¶

set_application_context(application_context) ¶

post_process(pod) ¶

spakky.plugins.fastapi.post_processors.register_routes ¶

RegisterRoutesPostProcessor ¶

set_container(container) ¶

set_application_context(application_context) ¶

post_process(pod) ¶

spakky.plugins.fastapi.post_processors.register_actuator ¶

RegisterActuatorPostProcessor ¶

set_container(container) ¶

post_process(pod) ¶

Actuator¶

spakky.plugins.fastapi.actuator ¶

FastAPIActuatorConfig(*, enabled=True, base_path='/actuator', health_enabled=True, readiness_enabled=True, liveness_enabled=True, info_enabled=True) ¶

에러¶

spakky.plugins.fastapi.error ¶

AbstractSpakkyFastAPIError ¶

status_code class-attribute ¶

to_response(show_traceback=False) ¶

BadRequest ¶

Unauthorized ¶

Forbidden ¶

NotFound ¶

Conflict ¶

InternalServerError ¶

플러그인 진입점¶

spakky.plugins.fastapi.main ¶

initialize(app) ¶

`spakky.plugins.fastapi.stereotypes.api_controller` ¶

`ApiController(prefix, tags=None, *, name='', scope=Scope.SINGLETON)` `dataclass` ¶

`prefix` `instance-attribute` ¶

`tags = None` `class-attribute` `instance-attribute` ¶

`spakky.plugins.fastapi.routes.route` ¶

`HTTPMethod` ¶

`repr()` ¶

`spakky.plugins.fastapi.routes.get` ¶

`spakky.plugins.fastapi.routes.post` ¶

`spakky.plugins.fastapi.routes.put` ¶

`spakky.plugins.fastapi.routes.patch` ¶

`spakky.plugins.fastapi.routes.delete` ¶

`spakky.plugins.fastapi.routes.head` ¶

`spakky.plugins.fastapi.routes.options` ¶

`spakky.plugins.fastapi.routes.websocket` ¶

`WebSocketRoute(path, name=None, dependencies=None)` `dataclass` ¶

`websocket(path, name=None, dependencies=None)` ¶

`spakky.plugins.fastapi.middlewares.error_handling` ¶

`ErrorHandlingMiddleware(app, dispatch=None, debug=False)` ¶

`dispatch(request, call_next)` `async` ¶

`spakky.plugins.fastapi.middlewares.tracing` ¶

`TracingMiddleware(app, dispatch=None, *, propagator)` ¶

`dispatch(request, call_next)` `async` ¶

`spakky.plugins.fastapi.post_processors.bind_lifespan` ¶

`BindLifespanPostProcessor` ¶

`set_application_context(application_context)` ¶

`post_process(pod)` ¶

`spakky.plugins.fastapi.post_processors.add_builtin_middlewares` ¶

`AddBuiltInMiddlewaresPostProcessor` ¶

`set_application_context(application_context)` ¶

`post_process(pod)` ¶

`spakky.plugins.fastapi.post_processors.register_routes` ¶

`RegisterRoutesPostProcessor` ¶

`set_container(container)` ¶

`set_application_context(application_context)` ¶

`post_process(pod)` ¶

`spakky.plugins.fastapi.post_processors.register_actuator` ¶

`RegisterActuatorPostProcessor` ¶

`set_container(container)` ¶

`post_process(pod)` ¶

`spakky.plugins.fastapi.actuator` ¶

`FastAPIActuatorConfig(*, enabled=True, base_path='/actuator', health_enabled=True, readiness_enabled=True, liveness_enabled=True, info_enabled=True)` ¶

`spakky.plugins.fastapi.error` ¶

`AbstractSpakkyFastAPIError` ¶

`status_code` `class-attribute` ¶

`to_response(show_traceback=False)` ¶

`BadRequest` ¶

`Unauthorized` ¶

`Forbidden` ¶

`NotFound` ¶

`Conflict` ¶

`InternalServerError` ¶

`spakky.plugins.fastapi.main` ¶

`initialize(app)` ¶