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.

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.

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.

openapi_controller: type[OpenAPIController]#

Controller for generating OpenAPI routes.

Must be subclass of OpenAPIController.

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.

__init__(title: str, version: str, create_examples: bool = False, random_seed: int = 10, openapi_controller: type[OpenAPIController] = <factory>, 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, root_schema_site: Literal['redoc', 'swagger', 'elements', 'rapidoc'] = 'redoc', enabled_endpoints: set[str] = <factory>, operation_id_creator: OperationIDCreator = <function default_operation_id_creator>, path: str | None = None) None#
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.

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.

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

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

enabled_endpoints: set[str]#

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

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.

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 = MediaType.JSON, examples: list[Example] | None = None) None#
description: str = 'Additional response'#

A description of the response.

media_type: MediaType = 'application/json'#

Response media type.

examples: list[Example] | None = None#

A list of Example models.