openapi#

class litestar.openapi.OpenAPIController#

Bases: Controller

Controller for OpenAPI endpoints.

path: str#

Base path for the OpenAPI documentation endpoints.

style: str = 'body { margin: 0; padding: 0 }'#

Base styling of the html body.

redoc_version: str = 'next'#

Redoc version to download from the CDN.

swagger_ui_version: str = '5.1.3'#

SwaggerUI version to download from the CDN.

stoplight_elements_version: str = '7.7.18'#

StopLight Elements version to download from the CDN.

rapidoc_version: str = '9.3.4'#

RapiDoc version to download from the CDN.

favicon_url: str = ''#

URL to download a favicon from.

redoc_google_fonts: bool = True#

Download google fonts via CDN.

Should be set to False when not using a CDN.

redoc_js_url: str = 'https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js'#

Download url for the Redoc JS bundle.

swagger_css_url: str = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.1.3/swagger-ui.css'#

Download url for the Swagger UI CSS bundle.

swagger_ui_bundle_js_url: str = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.1.3/swagger-ui-bundle.js'#

Download url for the Swagger UI JS bundle.

swagger_ui_standalone_preset_js_url: str = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.1.3/swagger-ui-standalone-preset.js'#

Download url for the Swagger Standalone Preset JS bundle.

swagger_ui_init_oauth: dict[Any, Any] | bytes = {}#

JSON to initialize Swagger UI OAuth2 by calling the initOAuth method.

Refer to the following URL for details: Swagger-UI.

stoplight_elements_css_url: str = 'https://unpkg.com/@stoplight/elements@7.7.18/styles.min.css'#

Download url for the Stoplight Elements CSS bundle.

stoplight_elements_js_url: str = 'https://unpkg.com/@stoplight/elements@7.7.18/web-components.min.js'#

Download url for the Stoplight Elements JS bundle.

rapidoc_js_url: str = 'https://unpkg.com/rapidoc@9.3.4/dist/rapidoc-min.js'#

Download url for the RapiDoc JS bundle.

dto: type[AbstractDTO] | None | EmptyType#

AbstractDTO to use for (de)serializing and validation of request data.

return_dto: type[AbstractDTO] | None | EmptyType#

AbstractDTO to use for serializing outbound response data.

static get_schema_from_request(request: Request[Any, Any, Any]) OpenAPI#

Return the OpenAPI pydantic model from the request instance.

Parameters:

request – A Litestar instance.

Returns:

An OpenAPI instance.

should_serve_endpoint(request: Request[Any, Any, Any]) bool#

Verify that the requested path is within the enabled endpoints in the openapi_config.

Parameters:

request – To be tested if endpoint enabled.

Returns:

A boolean.

Raises:

ImproperlyConfiguredException – If the application openapi_config attribute is None.

property favicon: str#

Return favicon <link> tag, if applicable.

Returns:

A <link> tag if self.favicon_url is not empty, otherwise returns a placeholder meta tag.

after_request: AfterRequestHookHandler | None#

A sync or async function executed before a Request is passed to any route handler.

If this function returns a value, the request will not reach the route handler, and instead this value will be used.

after_response: AfterResponseHookHandler | None#

A sync or async function called after the response has been awaited.

It receives the Request instance and should not return any values.

before_request: BeforeRequestHookHandler | None#

A sync or async function called immediately before calling the route handler.

It receives the Request instance and any non-None return value is used for the response, bypassing the route handler.

cache_control: CacheControlHeader | None#

A CacheControlHeader header to add to route handlers of this controller.

Can be overridden by route handlers.

dependencies: Dependencies | None#

A string keyed dictionary of dependency Provider instances.

etag: ETag | None#

An etag header of type ETag to add to route handlers of this controller.

Can be overridden by route handlers.

exception_handlers: ExceptionHandlersMap | None#

A map of handler functions to status codes and/or exception types.

guards: Sequence[Guard] | None#

A sequence of Guard callables.

include_in_schema: bool | EmptyType#

A boolean flag dictating whether the route handler should be documented in the OpenAPI schema

middleware: Sequence[Middleware] | None#

A sequence of Middleware.

opt: Mapping[str, Any] | None#

A string key mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.

owner: Router#

The Router or Litestar app that owns the controller.

This value is set internally by Litestar and it should not be set when subclassing the controller.

parameters: ParametersMap | None#

A mapping of Parameter definitions available to all application paths.

request_class: type[Request] | None#

A custom subclass of Request to be used as the default request for all route handlers under the controller.

response_class: type[Response] | None#

A custom subclass of Response to be used as the default response for all route handlers under the controller.

response_cookies: ResponseCookies | None#

A list of Cookie instances.

response_headers: ResponseHeaders | None#

A string keyed dictionary mapping ResponseHeader instances.

security: Sequence[SecurityRequirement] | None#

A sequence of dictionaries that to the schema of all route handlers under the controller.

signature_namespace: dict[str, Any]#

A mapping of names to types for use in forward reference resolution during signature modeling.

signature_types: Sequence[Any]#

A sequence of types for use in forward reference resolution during signature modeling.

These types will be added to the signature namespace using their __name__ attribute.

tags: Sequence[str] | None#

A sequence of string tags that will be appended to the schema of all route handlers under the controller.

type_encoders: TypeEncodersMap | None#

A mapping of types to callables that transform them into types supported for serialization.

type_decoders: TypeDecodersSequence | None#

A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.

websocket_class: type[WebSocket] | None#

A custom subclass of WebSocket to be used as the default websocket for all route handlers under the controller.

property render_methods_map: dict[Literal['redoc', 'swagger', 'elements', 'rapidoc'], Callable[[Request], bytes]]#

Map render method names to render methods.

Returns:

A mapping of string keys to render methods.

render_swagger_ui_oauth2_redirect(request: Request[Any, Any, Any]) bytes#

Render an HTML oauth2-redirect.html page for Swagger-UI.

Notes

  • override this method to customize the template.

Parameters:

request – A Request instance.

Returns:

A rendered html string.

render_swagger_ui(request: Request[Any, Any, Any]) bytes#

Render an HTML page for Swagger-UI.

Notes

  • override this method to customize the template.

Parameters:

request – A Request instance.

Returns:

A rendered html string.

render_stoplight_elements(request: Request[Any, Any, Any]) bytes#

Render an HTML page for StopLight Elements.

Notes

  • override this method to customize the template.

Parameters:

request – A Request instance.

Returns:

A rendered html string.

render_redoc(request: Request[Any, Any, Any]) bytes#

Render an HTML page for Redoc.

Notes

  • override this method to customize the template.

Parameters:

request – A Request instance.

Returns:

A rendered html string.

render_404_page() bytes#

Render an HTML 404 page.

Returns:

A rendered html string.

class litestar.openapi.OpenAPIConfig#

Bases: object

Configuration for OpenAPI.

To enable OpenAPI schema generation and serving, pass an instance of this class to the Litestar constructor using the openapi_config kwargs.

title: str#

Title of API documentation.

version: str#

API version, e.g. ‘1.0.0’.

create_examples: bool = False#

Generate examples using the polyfactory library.

random_seed: int = 10#

The random seed used when creating the examples to ensure deterministic generation of examples.

contact: Contact | None = None#

API contact information, should be an Contact instance.

description: str | None = None#

API description.

external_docs: ExternalDocumentation | None = None#

Links to external documentation.

Should be an instance of ExternalDocumentation.

license: License | None = None#

API Licensing information.

Should be an instance of License.

security: list[SecurityRequirement] | None = None#

API Security requirements information.

Should be an instance of

SecurityRequirement.

components: Components | list[Components]#

API Components information.

Should be an instance of Components or a list thereof.

servers: list[Server]#

A list of Server instances.

summary: str | None = None#

A summary text.

tags: list[Tag] | None = None#

A list of Tag instances.

__init__(title: str, version: str, create_examples: bool = False, random_seed: int = 10, contact: Contact | None = None, description: str | None = None, external_docs: ExternalDocumentation | None = None, license: License | None = None, security: list[SecurityRequirement] | None = None, components: Components | list[Components] = <factory>, servers: list[Server] = <factory>, summary: str | None = None, tags: list[Tag] | None = None, terms_of_service: str | None = None, use_handler_docstrings: bool = False, webhooks: dict[str, PathItem | Reference] | None = None, operation_id_creator: OperationIDCreator = <function default_operation_id_creator>, path: str | None = None, render_plugins: Sequence[OpenAPIRenderPlugin] = (), openapi_router: Router | None = None, openapi_controller: type[OpenAPIController] | None = None, root_schema_site: Literal['redoc', 'swagger', 'elements', 'rapidoc'] | None = None, enabled_endpoints: set[str] | None = None) None#
terms_of_service: str | None = None#

URL to page that contains terms of service.

use_handler_docstrings: bool = False#

Draw operation description from route handler docstring if not otherwise provided.

webhooks: dict[str, PathItem | Reference] | None = None#

A mapping of key to either PathItem or.

Reference objects.

operation_id_creator(http_method: Method, path_components: list[str | PathParameterDefinition]) str#

A callable that generates unique operation ids

path: str | None = None#

Base path for the OpenAPI documentation endpoints.

If no path is provided the default is /schema.

Ignored if openapi_router is provided.

render_plugins: Sequence[OpenAPIRenderPlugin] = ()#

Plugins for rendering OpenAPI documentation UIs.

openapi_router: Router | None = None#

An optional router for serving OpenAPI documentation and schema files.

If provided, path is ignored.

This parameter is also ignored if the deprecated openapi_router kwarg is provided.

openapi_router is not required, but it can be passed to customize the configuration of the router used to serve the documentation endpoints. For example, you can add middleware or guards to the router.

Handlers to serve the OpenAPI schema and documentation sites are added to this router according to render_plugins, so routes shouldn’t be added that conflict with these.

openapi_controller: type[OpenAPIController] | None = None#

Controller for generating OpenAPI routes.

Must be subclass of OpenAPIController.

Deprecated since version v2.8.0.

root_schema_site: Literal['redoc', 'swagger', 'elements', 'rapidoc'] | None = None#

The static schema generator to use for the “root” path of /schema/.

Deprecated since version v2.8.0.

enabled_endpoints: set[str] | None = None#

A set of the enabled documentation sites and schema download endpoints.

Deprecated since version v2.8.0.

to_openapi_schema() OpenAPI#

Return an OpenAPI instance from the values stored in self.

Returns:

An instance of OpenAPI.

class litestar.openapi.ResponseSpec#

Bases: object

Container type of additional responses.

data_container: DataContainerType | None#

A model that describes the content of the response.

generate_examples: bool = True#

Generate examples for the response content.

__init__(data_container: DataContainerType | None, generate_examples: bool = True, description: str = 'Additional response', media_type: MediaType | str = MediaType.JSON, examples: list[Example] | None = None) None#
description: str = 'Additional response'#

A description of the response.

media_type: MediaType | str = 'application/json'#

Response media type.

examples: list[Example] | None = None#

A list of Example models.