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.

__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

contact: Contact | None = None

API contact information, should be an Contact instance.

create_examples: bool = False

Generate examples using the polyfactory library.

description: str | None = None

API description.

enabled_endpoints: set[str] | None = None

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

Deprecated since version v2.8.0.

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.

openapi_controller: type[OpenAPIController] | None = None

Controller for generating OpenAPI routes.

Must be subclass of OpenAPIController.

Deprecated since version v2.8.0.

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.

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

Create a unique ‘operationId’ for an OpenAPI PathItem entry.

Parameters:

• route_handler – The HTTP Route Handler instance.

• http_method – The HTTP method for the given PathItem.

• path_components – A list of path components.

Returns:

A camelCased operationId created from the handler function name, http method and path components.

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.

random_seed: int = 10

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

render_plugins: Sequence[OpenAPIRenderPlugin] = ()

Plugins for rendering OpenAPI documentation UIs.

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.

security: list[SecurityRequirement] | None = None

API Security requirements information.

Should be an instance of

SecurityRequirement.

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.

to_openapi_schema() → OpenAPI

Return an OpenAPI instance from the values stored in self.

Returns:

An instance of OpenAPI.

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.

title: str

Title of API documentation.

version: str

API version, e.g. ‘1.0.0’.

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.

class litestar.openapi.OpenAPIController

Bases: Controller

Controller for OpenAPI endpoints.

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.

dto: type[AbstractDTO] | None | EmptyType

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

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.

path: str

Base path for the OpenAPI documentation endpoints.

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.

return_dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for serializing outbound response data.

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

favicon_url: str = ''

URL to download a favicon from.

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.

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

Download url for the RapiDoc JS bundle.

rapidoc_version: str = '9.3.4'

RapiDoc version to download from the CDN.

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.

redoc_version: str = 'next'

Redoc version to download from the CDN.

render_404_page() → bytes

Render an HTML 404 page.

Returns:

A rendered html string.

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

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.

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.

stoplight_elements_version: str = '7.7.18'

StopLight Elements version to download from the CDN.

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

Base styling of the html body.

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

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_version: str = '5.18.2'

SwaggerUI version to download from the CDN.

class litestar.openapi.ResponseSpec

Bases: object

Container type of additional responses.

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

examples: list[Example] | None = None

A list of Example models.

generate_examples: bool = True

Generate examples for the response content.

media_type: MediaType | str = 'application/json'

Response media type.

data_container: DataContainerType | None

A model that describes the content of the response.