OpenAPI integration#
Litestar has first class OpenAPI support offering the following features:
Automatic OpenAPI 3.1.0 Schema generation, which is available as both YAML and JSON.
Builtin support for static documentation site generation using several different libraries.
Simple configuration using pydantic based classes.
Litestar includes a complete implementation of the latest version of the OpenAPI specification using Python dataclasses. This implementation is used as a basis for generating OpenAPI specs, supporting builtins including dataclasses and TypedDict, as well as Pydantic models and any 3rd party entities for which a plugin is implemented.
This is also highly configurable - and users can customize the OpenAPI spec in a variety of ways - ranging from passing configuration globally, to settings specific kwargs on route handler decorators.
OpenAPI schema generation config#
OpenAPI schema generation is enabled by default. To configure it you can pass an instance of
OpenAPIConfig to the Litestar class using the
openapi_config kwarg:
from litestar import Litestar
from litestar.openapi import OpenAPIConfig
app = Litestar(
route_handlers=[...], openapi_config=OpenAPIConfig(title="My API", version="1.0.0")
)
Disabling schema generation#
If you wish to disable schema generation and not include the schema endpoints in your API, simply pass None as the
value for openapi_config:
from litestar import Litestar
app = Litestar(route_handlers=[...], openapi_config=None)
Route handler OpenAPI configuration#
By default, an operation schema is generated for all route
handlers. You can omit a route handler from the schema by setting include_in_schema=False:
from litestar import get
@get(path="/some-path", include_in_schema=False)
def my_route_handler() -> None:
...
You can also modify the generated schema for the route handler using the following kwargs:
tagsA list of strings that correlate to the tag specification.
security:A list of dictionaries that correlate to the security requirements specification. The values for this key are string keyed dictionaries with the values being a list of objects.
summaryText used for the route’s schema summary section.
descriptionText used for the route’s schema description section.
response_descriptionText used for the route’s response schema description section.
operation_idAn identifier used for the route’s schema operationId. Defaults to the
__name__attribute of the wrapped function.deprecatedA boolean dictating whether this route should be marked as deprecated in the OpenAPI schema. Defaults to
False.raisesA list of exception classes extending from
litestar.HttpException. This list should describe all exceptions raised within the route handler’s function/method. The LitestarValidationExceptionwill be added automatically for the schema if any validation is involved (e.g. there are parameters specified in the method/function).responsesA dictionary of additional status codes and a description of their expected content. The expected content should be based on a Pydantic model describing its structure. It can also include a description and the expected media type. For example:
Note
operation_id will be prefixed with the method name when function is decorated with HTTPRouteHandler and multiple http_method. Will also be prefixed with path strings used in Routers and Controllers to make sure id is unique.
from datetime import datetime
from typing import Optional
from pydantic import BaseModel
from litestar import get
from litestar.openapi.datastructures import ResponseSpec
class Item(BaseModel):
...
class ItemNotFound(BaseModel):
was_removed: bool
removed_at: Optional[datetime]
@get(
path="/items/{pk:int}",
responses={
404: ResponseSpec(
model=ItemNotFound, description="Item was removed or not found"
)
},
)
def retrieve_item(pk: int) -> Item:
...
from datetime import datetime
from pydantic import BaseModel
from litestar import get
from litestar.openapi.datastructures import ResponseSpec
class Item(BaseModel):
...
class ItemNotFound(BaseModel):
was_removed: bool
removed_at: datetime | None
@get(
path="/items/{pk:int}",
responses={
404: ResponseSpec(
model=ItemNotFound, description="Item was removed or not found"
)
},
)
def retrieve_item(pk: int) -> Item:
...
You can also specify security and tags on higher level of the application, e.g. on a controller, router or the
app instance itself. For example:
from litestar import Litestar, get
from litestar.openapi import OpenAPIConfig
from litestar.openapi.spec import Components, SecurityScheme, Tag
@get(
"/public",
tags=["public"],
security=[{}], # this endpoint is marked as having optional security
)
def public_path_handler() -> dict[str, str]:
return {"hello": "world"}
@get("/other", tags=["internal"], security=[{"apiKey": []}])
def internal_path_handler() -> None:
...
app = Litestar(
route_handlers=[public_path_handler, internal_path_handler],
openapi_config=OpenAPIConfig(
title="my api",
version="1.0.0",
tags=[
Tag(name="public", description="This endpoint is for external users"),
Tag(name="internal", description="This endpoint is for internal users"),
],
security=[{"BearerToken": []}],
components=Components(
securitySchemes={
"BearerToken": SecurityScheme(
type="http",
scheme="bearer",
)
},
),
),
)
The OpenAPIController#
Litestar includes an OpenAPIController class that is used as the
default controller in the OpenAPIConfig.
This controller exposes the following endpoints:
/schema/openapi.yamlallowing for download of the OpenAPI schema as YAML.
/schema/openapi.jsonallowing for download of the OpenAPI schema as JSON.
/schema/redocServes the docs using Redoc.
/schema/swaggerServes the docs using Swagger-UI.
/schema/elementsServes the docs using Stoplight Elements.
Additionally, the root /schema/ path is accessible, serving the site that is configured as the default in
the OpenAPIConfig.
Subclassing OpenAPIController#
You can use your own subclass of OpenAPIController by setting it as
the controller to use in the OpenAPIConfig openapi_controller kwarg.
For example, lets say we wanted to change the base path of the OpenAPI related endpoints from /schema to
/api-docs, in this case we’d the following:
from litestar import Litestar
from litestar.openapi import OpenAPIConfig
from litestar.openapi import OpenAPIController
class MyOpenAPIController(OpenAPIController):
path = "/api-docs"
app = Litestar(
route_handlers=[...],
openapi_config=OpenAPIConfig(
title="My API", version="1.0.0", openapi_controller=MyOpenAPIController
),
)
CDN and offline file support#
You can change the default download paths for JS and CSS bundles as well as google fonts by subclassing
OpenAPIController and setting any of the following class variables:
from litestar import Litestar
from litestar.openapi import OpenAPIConfig
from litestar.openapi import OpenAPIController
class MyOpenAPIController(OpenAPIController):
path = "/api-docs"
redoc_google_fonts = False
redoc_js_url = "https://offline_location/redoc.standalone.js"
swagger_css_url = "https://offline_location/swagger-ui-css"
swagger_ui_bundle_js_url = "https://offline_location/swagger-ui-bundle.js"
swagger_ui_standalone_preset_js_url = (
"https://offline_location/swagger-ui-standalone-preset.js"
)
stoplight_elements_css_url = "https://offline_location/spotlight-styles.mins.css"
stoplight_elements_js_url = (
"https://offline_location/spotlight-web-components.min.js"
)
app = Litestar(
route_handlers=[...],
openapi_config=OpenAPIConfig(
title="My API", version="1.0.0", openapi_controller=MyOpenAPIController
),
)
Accessing the OpenAPI schema in code#
The OpenAPI schema is generated during the Litestar app’s init method. Once init is finished,
its accessible as app.openapi_schema. As such you can always access it inside route handlers, dependencies etc. by
access the request instance:
from litestar import Request, get
@get(path="/")
def my_route_handler(request: Request) -> dict:
schema = request.app.openapi_schema
return schema.dict()
Customizing Pydantic model schemas#
You can customize the OpenAPI schemas generated for pydantic models by following the guidelines in the pydantic docs.
Additionally, you can affect how pydantic models are translated into OpenAPI components by settings a special dunder
attribute on the model called __schema_name__:
from uuid import UUID, uuid4
from pydantic import BaseModel
from litestar import Litestar, get
class IdModel(BaseModel):
__schema_name__ = "IdContainer"
id: UUID
@get("/id", sync_to_thread=False)
def retrieve_id_handler() -> IdModel:
"""
Returns: An IdModel
"""
return IdModel(id=uuid4())
app = Litestar(route_handlers=[retrieve_id_handler])
The above will result in an OpenAPI schema object that looks like this:
{
"openapi": "3.1.0",
"info": {"title": "Litestar API", "version": "1.0.0"},
"servers": [{"url": "/"}],
"paths": {
"/id": {
"get": {
"operationId": "Retrieve Id Handler",
"responses": {
"200": {
"description": "Request fulfilled, document follows",
"headers": {},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdContainer"
}
}
}
}
},
"deprecated": false
}
}
},
"components": {
"schemas": {
"IdContainer": {
"properties": {
"id": {"type": "string", "format": "uuid", "title": "Id"}
},
"type": "object",
"required": ["id"],
"title": "IdContainer"
}
}
}
}
Attention
If you use multiple pydantic models that use the same name in the schema, you will need to use the __schema_name__ dunder to ensure each has a unique name in the schema, otherwise the schema components will be ambivalent.