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.

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.

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.

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.

servers: list[Server]

A list of Server instances.

__init__(title: str, version: str, create_examples: bool = False, 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

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

A model that describes the content of the response.

generate_examples: bool = True

Generate examples for the response content.

__init__(data_container: DataContainerType, generate_examples: bool = True, description: str = 'Additional response', media_type: MediaType = MediaType.JSON) → None

description: str = 'Additional response'

A description of the response.

media_type: MediaType = 'application/json'

Response media type.