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 = '/schema', render_plugins: Sequence[OpenAPIRenderPlugin] = (<litestar.openapi.plugins.ScalarRenderPlugin object>, ), openapi_router: Router | 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.

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_router: Router | None = None

An optional router for serving OpenAPI documentation and schema files.

If provided, path is ignored.

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 = '/schema'

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] = (<litestar.openapi.plugins.ScalarRenderPlugin object>,)

Plugins for rendering OpenAPI documentation UIs.

Changed in version 3.0.0: Default behavior changed to serve only ScalarRenderPlugin.

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