openapi

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.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.18.2'

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.18.2/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.18.2/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.18.2/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.

request_max_body_size: int | None | EmptyType

Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.

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 modelling.

signature_types: Sequence[Any]

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

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_decoders: TypeDecodersSequence | None

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

type_encoders: TypeEncodersMap | None

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

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.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.