Debian Codegraph @

docs/usage/openapi/ui_plugins.rst

raw
1 OpenAPI UI Plugins
2 ------------------
3
4 .. versionadded:: 2.8.0
5
6 OpenAPI UI Plugins are designed to allow easy integration with your OpenAPI UI framework of choice. These plugins
7 facilitate the creation of interactive, user-friendly API documentation, making it easier for developers and end-users
8 to understand and interact with your API.
9
10 Litestar maintains and ships with UI plugins for a range of popular popular OpenAPI documentation tools:
11
12 - `Scalar <https://github.com/scalar/scalar/>`_
13 - `RapiDoc <https://rapidocweb.com/>`_
14 - `ReDoc <https://redocly.com/>`_
15 - `Stoplight Elements <https://stoplight.io/open-source/elements>`_
16 - `Swagger UI <https://swagger.io/tools/swagger-ui/>`_
17 - `YAML <https://yaml.org/>`_
18
19 Each plugin is easily configurable, allowing developers to customize aspects like version, paths, CSS and JavaScript
20 resources.
21
22
23 Using OpenAPI UI Plugins
24 ------------------------
25
26 Using OpenAPI UI Plugins is as simple as importing the plugin, instantiating it, and adding it to the OpenAPIConfig.
27
28 .. tab-set::
29
30 .. tab-item:: scalar
31 :sync: scalar
32
33 .. literalinclude:: /examples/openapi/plugins/scalar_simple.py
34 :language: python
35
36 .. tab-item:: rapidoc
37 :sync: rapidoc
38
39 .. literalinclude:: /examples/openapi/plugins/rapidoc_simple.py
40 :language: python
41
42 .. tab-item:: redoc
43 :sync: redoc
44
45 .. literalinclude:: /examples/openapi/plugins/redoc_simple.py
46 :language: python
47
48 .. tab-item:: stoplight
49 :sync: stoplight
50
51 .. literalinclude:: /examples/openapi/plugins/stoplight_simple.py
52 :language: python
53
54 .. tab-item:: swagger
55 :sync: swagger
56
57 .. literalinclude:: /examples/openapi/plugins/swagger_ui_simple.py
58 :language: python
59
60 .. tab-item:: yaml
61 :sync: yaml
62
63 .. literalinclude:: /examples/openapi/plugins/yaml_simple.py
64 :language: python
65
66 .. tab-item:: multiple
67
68 .. literalinclude:: /examples/openapi/plugins/serving_multiple_uis.py
69 :caption: Any combination of UIs can be served.
70 :language: python
71
72 Configuring OpenAPI UI Plugins
73 ------------------------------
74
75 Each plugin can be tailored to meet your unique requirements by passing options at instantiation. For full details on
76 each plugin's options, see the :doc:`API Reference </reference/openapi/plugins>`.
77
78 All plugins support:
79
80 - ``path``: Each plugin has its own default, e.g., ``/rapidoc`` for RapiDoc. This can be overridden to serve the UI at
81 a different path.
82 - ``media_type``: The default media type for the plugin, typically the default is ``text/html``.
83 - ``favicon``: A string that should be a valid ``<link>`` tag, e.g.,
84 ``<link rel="icon" href="https://example.com/favicon.ico">``.
85 - ``style``: A string that should be a valid ``<style>`` tag, e.g., ``<style>body { margin: 0; padding: 0; }``</style>.``
86
87 Most plugins support the following additional options:
88
89 - ``version``: The version of the UIs JS and (in some cases) CSS bundle to use. We use the ``version`` to construct the
90 URL to retrieve the bundle from ``unpkg``, e.g., ``https://unpkg.com/rapidoc@<version>/dist/rapidoc-min.js``
91 - ``js_url``: The URL to the JS bundle. If provided, this will override the ``version`` option.
92 - ``css_url``: The URL to the CSS bundle. If provided, this will override the ``version`` option.
93
94 Here's some example plugin configurations:
95
96 .. tab-set::
97
98 .. tab-item:: scalar
99 :sync: scalar
100
101 .. literalinclude:: /examples/openapi/plugins/scalar_config.py
102 :language: python
103
104 .. tab-item:: rapidoc
105 :sync: rapidoc
106
107 .. literalinclude:: /examples/openapi/plugins/rapidoc_config.py
108 :language: python
109
110 .. tab-item:: redoc
111 :sync: redoc
112
113 .. literalinclude:: /examples/openapi/plugins/redoc_config.py
114 :language: python
115
116 .. tip::
117
118 Setting ``js_url`` lets you point the ReDoc bundle to any CDN or internal host. In ``redoc_config.py``
119 we override it to ``https://cdn.company.internal/redoc/custom-redoc.js``. When provided, ``js_url`` takes
120 precedence over ``version``.
121
122 .. tab-item:: stoplight
123 :sync: stoplight
124
125 .. literalinclude:: /examples/openapi/plugins/stoplight_config.py
126 :language: python
127
128 .. tab-item:: swagger
129 :sync: swagger
130
131 .. literalinclude:: /examples/openapi/plugins/swagger_ui_config.py
132 :language: python
133
134 Configuring the OpenAPI Root Path
135 ---------------------------------
136
137 The OpenAPI root path is the path at which the OpenAPI representations are served. By default, this is ``/schema``.
138 This can be changed by setting the :attr:`OpenAPIConfig.path` attribute.
139
140 In the following example, we configure the OpenAPI root path to be ``/docs``:
141
142 .. literalinclude:: /examples/openapi/customize_path.py
143 :language: python
144
145 This will result in any of the OpenAPI endpoints being served at ``/docs`` instead of ``/schema``, e.g.,
146 ``/docs/openapi.json``.
147
148 Backward Compatibility
149 ----------------------
150
151 OpenAPI UI plugins are a new feature introduced in ``v2.8.0``.
152
153 Providing a subclass of OpenAPIController
154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155
156 .. deprecated:: v2.8.0
157
158 The previous method of configuring elements such as the root path and styling was to subclass
159 :class:`OpenAPIController`, and set it on the :attr:`OpenAPIConfig.openapi_controller` attribute. This approach is now
160 deprecated and slated for removal in ``v3.0.0``, but if you are using it, there should be no change in behavior.
161
162 To maintain backward compatibility with the previous approach, if neither the :attr:`OpenAPIConfig.openapi_controller`
163 or :attr:`OpenAPIConfig.render_plugins` attributes are set, we will automatically add the plugins to respect the also
164 deprecated :attr:`OpenAPIConfig.enabled_endpoints` attribute. By default, this will result in the following endpoints
165 being enabled:
166
167 - ``/schema/openapi.json``
168 - ``/schema/redoc``
169 - ``/schema/rapidoc``
170 - ``/schema/elements``
171 - ``/schema/swagger``
172 - ``/schema/openapi.yml``
173 - ``/schema/openapi.yaml``
174
175 In ``v3.0.0``, the :attr:`OpenAPIConfig.enabled_endpoints` attribute will be removed, and only a single UI plugin will be
176 enabled by default, in addition to the ``openapi.json`` endpoint which will always be enabled. ``Scalar`` will also
177 become the default UI plugin in ``v3.0.0``.
178
179 To adopt the future behavior, explicitly set the :attr:`OpenAPIConfig.render_plugins` field to an instance of
180 :class:`ScalarRenderPlugin`:
181
182 .. literalinclude:: /examples/openapi/plugins/scalar_simple.py
183 :language: python
184 :lines: 13-21
185
186 Backward compatibility with ``root_schema_site``
187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
189 Litestar has always supported a ``root_schema_site`` attribute on the :class:`OpenAPIConfig` class. This attribute
190 allows you to elect to serve a UI at the OpenAPI root path, e.g., by default ``redoc`` would be served at both
191 ``/schema`` and ``/schema/redoc``.
192
193 In ``v3.0.0``, the ``root_schema_site`` attribute will be removed, and the first :class:`OpenAPIRenderPlugin` in the
194 :attr:`OpenAPIConfig.render_plugins` list will be assigned to the ``/schema`` endpoint.
195
196 As of ``v2.8.0``, if you explicitly use the new :attr:`OpenAPIConfig.render_plugins` attribute, you will be
197 automatically opted in to the new behavior, and the ``root_schema_site`` attribute will be ignored.
198
199 Building your own OpenAPI UI Plugin
200 -----------------------------------
201
202 If Litestar does not have built-in support for your OpenAPI UI framework of choice, you can easily create your own
203 plugin by subclassing :class:`OpenAPIRenderPlugin` and implementing the :meth:`OpenAPIRenderPlugin.render` method.
204
205 To demonstrate building a custom plugin, we'll look at a plugin very similar to the :class:`ScalarRenderPlugin` that is
206 maintained by Litestar. Here's the finished product:
207
208 .. literalinclude:: /examples/openapi/plugins/custom_plugin.py
209 :language: python
210
211 Class definition
212 ~~~~~~~~~~~~~~~~
213
214 The class ``ScalarRenderPlugin`` inherits from :class:`OpenAPIRenderPlugin`:
215
216 .. literalinclude:: /examples/openapi/plugins/custom_plugin.py
217 :language: python
218 :lines: 10
219
220 ``__init__`` Constructor
221 ~~~~~~~~~~~~~~~~~~~~~~~~
222
223 .. literalinclude:: /examples/openapi/plugins/custom_plugin.py
224 :language: python
225 :lines: 11-22
226
227 We support configuration via the following arguments:
228
229 - ``version``: Specifies the version of RapiDoc to use.
230 - ``js_url``: Custom URL to the RapiDoc JavaScript bundle.
231 - ``css_url``: Custom URL to the RapiDoc CSS bundle.
232 - ``path``: The URL path where the RapiDoc UI will be served.
233 - ``**kwargs``: Captures additional arguments to pass to the superclass.
234
235 And we construct a url for the Scalar JavaScript bundle if one is not provided:
236
237 .. literalinclude:: /examples/openapi/plugins/custom_plugin.py
238 :language: python
239 :lines: 20
240
241 ``render()``
242 ~~~~~~~~~~~~
243
244 .. literalinclude:: /examples/openapi/plugins/custom_plugin.py
245 :language: python
246 :lines: 24
247
248 Finally we define the ``render`` method, which is called by Litestar to render the UI. It receives the a
249 :class:`Request` object and the ``openapi_schema`` as a dictionary.
250
251 Inside the ``render`` method, we construct the HTML to render the UI, and return it as a string.
252
253 - ``head``: Defines the HTML ``<head>`` section, including the title from ``openapi_schema``, any additional styles
254 (``self.style``), the favicon and custom style sheet if one is provided:
255
256 .. literalinclude:: /examples/openapi/plugins/custom_plugin.py
257 :language: python
258 :lines: 25-35
259
260 - ``body``: Constructs the HTML ``<body>``, including a link to the OpenAPI JSON, and the JavaScript bundle:
261
262 .. literalinclude:: /examples/openapi/plugins/custom_plugin.py
263 :language: python
264 :lines: 37-43
265
266 - Finally, returns a complete HTML document (as a byte string), combining head and body.
267
268 .. literalinclude:: /examples/openapi/plugins/custom_plugin.py
269 :language: python
270 :lines: 45-51
271
272 Interacting with the ``Router``
273 -------------------------------
274
275 An instance of :class:`Router` is used to serve the OpenAPI endpoints and is made available to plugins via the
276 :meth:`OpenAPIRenderPlugin.receive_router` method.
277
278 This can be used for a variety of purposes, including adding additional routes to the ``Router``.
279
280 .. literalinclude:: /examples/openapi/plugins/receive_router.py
281 :language: python
282
283 OAuth2 in Swagger UI
284 --------------------
285
286 When using Swagger, OAuth2 settings can be configured via
287 :attr:`swagger_ui_init_oauth <litestar.openapi.controller.OpenAPIController.swagger_ui_init_oauth>`, which can be set to
288 a dictionary containing the parameters described in the Swagger UI documentation for OAuth2
289 `here <https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/>`_.
290
291 With that, you can preset your clientId or enable PKCE support.
292
293 .. literalinclude:: /examples/openapi/plugins/swagger_ui_oauth.py
294 :language: python
295
296 CDN and offline file support
297 ----------------------------
298
299 Each plugin supports ``js_url`` and ``css_url`` attributes, which can be used to specify a custom URL to the JavaScript.
300 These can be used to serve the JavaScript and CSS from a CDN, or to serve the files from a local directory.