From 4b796156b55c9585043a0b5cc59d47db672ad631 Mon Sep 17 00:00:00 2001 From: Peter Schutt Date: Fri, 22 Mar 2024 15:05:03 +1000 Subject: [PATCH] docs: improvement for openapi router config. (#3235) Adds deprecated directives for the deprecated parameters of the config. Adds some cross-references. --- litestar/openapi/config.py | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/litestar/openapi/config.py b/litestar/openapi/config.py index f1fd0acf12..ebb763eb47 100644 --- a/litestar/openapi/config.py +++ b/litestar/openapi/config.py @@ -115,7 +115,7 @@ class OpenAPIConfig: If no path is provided the default is ``/schema``. - Ignored if ``openapi_router`` is provided. + Ignored if :attr:`openapi_router` is provided. """ render_plugins: Sequence[OpenAPIRenderPlugin] = field(default=()) """Plugins for rendering OpenAPI documentation UIs.""" @@ -124,22 +124,32 @@ class OpenAPIConfig: If provided, ``path`` is ignored. - This parameter is also ignored if the deprecated :class:`OpenAPIConfig <.openapi.OpenAPIConfig>` ``openapi_controller`` kwarg is provided. + This parameter is also ignored if the deprecated :attr:`openapi_router <.openapi.OpenAPIConfig.openapi_controller>` + kwarg is provided. - The ``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. + :attr:`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 the ``render_plugins`` attribute, so routes shouldn't be added that conflict with these. + Handlers to serve the OpenAPI schema and documentation sites are added to this router according to + :attr:`render_plugins`, so routes shouldn't be added that conflict with these. """ openapi_controller: type[OpenAPIController] | None = None """Controller for generating OpenAPI routes. Must be subclass of :class:`OpenAPIController `. + + .. deprecated:: v2.8.0 """ root_schema_site: Literal["redoc", "swagger", "elements", "rapidoc"] | None = None - """The static schema generator to use for the "root" path of ``/schema/``.""" + """The static schema generator to use for the "root" path of ``/schema/``. + + .. deprecated:: v2.8.0 + """ enabled_endpoints: set[str] | None = None - """A set of the enabled documentation sites and schema download endpoints.""" + """A set of the enabled documentation sites and schema download endpoints. + + .. deprecated:: v2.8.0 + """ def __post_init__(self) -> None: self._issue_deprecations()