openapi#
- class litestar.openapi.OpenAPIController#
Bases:
Controller
Controller for OpenAPI endpoints.
- 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.
- 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 isNone
.
- property favicon: str#
Return favicon
<link>
tag, if applicable.- Returns:
A
<link>
tag ifself.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 typeETag
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.
- 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 toRequest
orASGI Scope
.
- owner: Router#
The
Router
orLitestar
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.
- 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 theopenapi_config
kwargs.- openapi_controller: type[OpenAPIController]#
Controller for generating OpenAPI routes.
Must be subclass of
OpenAPIController
.
- external_docs: ExternalDocumentation | None = None#
Links to external documentation.
Should be an instance of
ExternalDocumentation
.
- security: list[SecurityRequirement] | None = None#
API Security requirements information.
- Should be an instance of
- 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, 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 #
- 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.
- class litestar.openapi.ResponseSpec#
Bases:
object
Container type of additional responses.
- data_container: DataContainerType#
A model that describes the content of the response.