463 lines
14 KiB
ReStructuredText
463 lines
14 KiB
ReStructuredText
.. role:: python(code)
|
|
:language: python
|
|
|
|
.. |br| raw:: html
|
|
|
|
<br />
|
|
|
|
########
|
|
Settings
|
|
########
|
|
|
|
Settings are configurable in ``settings.py`` by defining ``SWAGGER_SETTINGS`` or ``REDOC_SETTINGS``.
|
|
|
|
Example:
|
|
|
|
**settings.py**
|
|
|
|
.. code-block:: python
|
|
|
|
SWAGGER_SETTINGS = {
|
|
'SECURITY_DEFINITIONS': {
|
|
'basic': {
|
|
'type': 'basic'
|
|
}
|
|
},
|
|
...
|
|
}
|
|
|
|
REDOC_SETTINGS = {
|
|
'LAZY_RENDERING': False,
|
|
...
|
|
}
|
|
|
|
.. _url-settings:
|
|
|
|
All settings which configure URLs (``LOGIN_URL``, ``SPEC_URL``, ``VALIDATOR_URL``, etc.) can accept several forms of
|
|
input:
|
|
|
|
* A view name: `urls.reverse()` will be used to reverse-resolve the name
|
|
* A 2-tuple of ``(view_name, kwargs)```: `urls.reverse()` will be used to reverse-resolve the name using the given
|
|
`kwargs`; `kwargs` must be a dict
|
|
* A 3-tuple of ``(view_name, args, kwargs)```: `urls.reverse()` will be used to reverse-resolve the name using the given
|
|
`args` and `kwargs`; `args`, `kwargs` must be a tuple/list and a dict respectively
|
|
* A URL, which will be used as-is
|
|
|
|
The possible settings and their default values are as follows:
|
|
|
|
****************
|
|
SWAGGER_SETTINGS
|
|
****************
|
|
|
|
.. _default-class-settings:
|
|
|
|
Default classes
|
|
===============
|
|
|
|
DEFAULT_GENERATOR_CLASS
|
|
-------------------------
|
|
|
|
:class:`~.generators.OpenAPISchemaGenerator` subclass that will be used by default for generating the final
|
|
:class:`.Schema` object. Can be overriden by the ``generator_class`` argument to :func:`.get_schema_view`.
|
|
|
|
**Default**: :class:`drf_yasg.generators.OpenAPISchemaGenerator`
|
|
|
|
DEFAULT_AUTO_SCHEMA_CLASS
|
|
-------------------------
|
|
|
|
:class:`~.inspectors.ViewInspector` subclass that will be used by default for generating :class:`.Operation`
|
|
objects when iterating over endpoints. Can be overriden by using the `auto_schema` argument of
|
|
:func:`@swagger_auto_schema <.swagger_auto_schema>` or by a ``swagger_schema`` attribute on the view class.
|
|
|
|
**Default**: :class:`drf_yasg.inspectors.SwaggerAutoSchema`
|
|
|
|
DEFAULT_FIELD_INSPECTORS
|
|
------------------------
|
|
|
|
List of :class:`~.inspectors.FieldInspector` subclasses that will be used by default for inspecting serializers and
|
|
serializer fields. Field inspectors given to :func:`@swagger_auto_schema <.swagger_auto_schema>` will be prepended
|
|
to this list.
|
|
|
|
**Default**: ``[`` |br| \
|
|
:class:`'drf_yasg.inspectors.CamelCaseJSONFilter' <.inspectors.CamelCaseJSONFilter>`, |br| \
|
|
:class:`'drf_yasg.inspectors.ReferencingSerializerInspector' <.inspectors.ReferencingSerializerInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.RelatedFieldInspector' <.inspectors.RelatedFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.ChoiceFieldInspector' <.inspectors.ChoiceFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.FileFieldInspector' <.inspectors.FileFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.DictFieldInspector' <.inspectors.DictFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.JSONFieldInspector' <.inspectors.JSONFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.HiddenFieldInspector' <.inspectors.HiddenFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.RecursiveFieldInspector' <.inspectors.RecursiveFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.SerializerMethodFieldInspector' <.inspectors.SerializerMethodFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.SimpleFieldInspector' <.inspectors.SimpleFieldInspector>`, |br| \
|
|
:class:`'drf_yasg.inspectors.StringDefaultFieldInspector' <.inspectors.StringDefaultFieldInspector>`, |br| \
|
|
``]``
|
|
|
|
DEFAULT_FILTER_INSPECTORS
|
|
-------------------------
|
|
|
|
List of :class:`~.inspectors.FilterInspector` subclasses that will be used by default for inspecting filter backends.
|
|
Filter inspectors given to :func:`@swagger_auto_schema <.swagger_auto_schema>` will be prepended to this list.
|
|
|
|
**Default**: ``[`` |br| \
|
|
:class:`'drf_yasg.inspectors.CoreAPICompatInspector' <.inspectors.CoreAPICompatInspector>`, |br| \
|
|
``]``
|
|
|
|
DEFAULT_PAGINATOR_INSPECTORS
|
|
----------------------------
|
|
|
|
List of :class:`~.inspectors.PaginatorInspector` subclasses that will be used by default for inspecting paginators.
|
|
Paginator inspectors given to :func:`@swagger_auto_schema <.swagger_auto_schema>` will be prepended to this list.
|
|
|
|
**Default**: ``[`` |br| \
|
|
:class:`'drf_yasg.inspectors.DjangoRestResponsePagination' <.inspectors.DjangoRestResponsePagination>`, |br| \
|
|
:class:`'drf_yasg.inspectors.CoreAPICompatInspector' <.inspectors.CoreAPICompatInspector>`, |br| \
|
|
``]``
|
|
|
|
Swagger document attributes
|
|
===========================
|
|
|
|
EXCLUDED_MEDIA_TYPES
|
|
--------------------
|
|
|
|
A list of keywords for excluding MIME types from ``Operation.produces``. Any MIME type string which includes one of
|
|
the substrings in this list will be prevented from appearing in a ``produces`` array in the Swagger document.
|
|
|
|
**Default**: :python:`['html']`
|
|
|
|
.. _default-swagger-settings:
|
|
|
|
DEFAULT_INFO
|
|
------------
|
|
|
|
An import string to an :class:`.openapi.Info` object. This will be used when running the ``generate_swagger``
|
|
management command, or if no ``info`` argument is passed to :func:`.get_schema_view`.
|
|
|
|
**Default**: :python:`None`
|
|
|
|
DEFAULT_API_URL
|
|
---------------
|
|
|
|
A string representing the default API URL. This will be used to populate the ``host`` and ``schemes`` attributes
|
|
of the Swagger document if no API URL is otherwise provided. The Django `FORCE_SCRIPT_NAME`_ setting can be used for
|
|
providing an API mount point prefix.
|
|
|
|
See also: :ref:`documentation on base URL construction <custom-spec-base-url>`
|
|
|
|
**Default**: :python:`None`
|
|
|
|
Authorization
|
|
=============
|
|
|
|
USE_SESSION_AUTH
|
|
----------------
|
|
|
|
Enable/disable Django login as an authentication/authorization mechanism. If True, a login/logout button will be
|
|
displayed in Swagger UI.
|
|
|
|
**Default**: :python:`True`
|
|
|
|
LOGIN_URL
|
|
---------
|
|
|
|
URL for the Django Login action when using `USE_SESSION_AUTH`_.
|
|
|
|
**Default**: :python:`django.conf.settings.LOGIN_URL`
|
|
|
|
LOGOUT_URL
|
|
----------
|
|
|
|
URL for the Django Logout action when using `USE_SESSION_AUTH`_.
|
|
|
|
**Default**: :python:`django.conf.settings.LOGOUT_URL`
|
|
|
|
.. _security-definitions-settings:
|
|
|
|
|
|
SECURITY_DEFINITIONS
|
|
--------------------
|
|
|
|
Swagger security definitions to be included in the specification. |br|
|
|
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-definitions-object.
|
|
|
|
**Default**:
|
|
|
|
.. code-block:: python
|
|
|
|
'basic': {
|
|
'type': 'basic'
|
|
}
|
|
|
|
SECURITY_REQUIREMENTS
|
|
---------------------
|
|
|
|
Global security requirements. If :python:`None`, all schemes in ``SECURITY_DEFINITIONS`` are accepted. |br|
|
|
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityRequirementObject.
|
|
|
|
**Default**: :python:`None`
|
|
|
|
.. _swagger-ui-settings:
|
|
|
|
Swagger UI settings
|
|
===================
|
|
|
|
Swagger UI configuration settings. |br|
|
|
See https://github.com/swagger-api/swagger-ui/blob/112bca906553a937ac67adc2e500bdeed96d067b/docs/usage/configuration.md#parameters.
|
|
|
|
SPEC_URL
|
|
--------
|
|
|
|
URL pointing to a swagger document for use by swagger-ui. The default behaviour is to append ``?format=openapi`` to the
|
|
URL which serves the UI; see :ref:`note on URL settings <url-settings>` above.
|
|
|
|
**Default**: :python:`None` |br|
|
|
*Maps to parameter*: ``url``
|
|
|
|
VALIDATOR_URL
|
|
-------------
|
|
|
|
URL pointing to a swagger-validator instance; used for the validation badge shown in swagger-ui. Can be modified to
|
|
point to a local install of `swagger-validator <https://hub.docker.com/r/swaggerapi/swagger-validator/>`_ or
|
|
set to ``None`` to remove the badge.
|
|
|
|
**Default**: :python:`'http://online.swagger.io/validator/'` |br|
|
|
*Maps to parameter*: ``validatorUrl``
|
|
|
|
PERSIST_AUTH
|
|
------------
|
|
|
|
Persist swagger-ui authorization data to local storage. |br|
|
|
**WARNING:** This may be a security risk as the credentials are stored unencrypted and can be accessed
|
|
by all javascript code running on the same domain.
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to parameter*: -
|
|
|
|
REFETCH_SCHEMA_WITH_AUTH
|
|
------------------------
|
|
|
|
Re-fetch the OpenAPI document with the new credentials after authorization is performed through swagger-ui.
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to parameter*: -
|
|
|
|
REFETCH_SCHEMA_ON_LOGOUT
|
|
------------------------
|
|
|
|
Re-fetch the OpenAPI document without credentials after authorization is removed through swagger-ui.
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to parameter*: -
|
|
|
|
FETCH_SCHEMA_WITH_QUERY
|
|
-----------------------
|
|
|
|
Fetch the OpenAPI document using the query parameters passed to the swagger-ui page request.
|
|
|
|
**Default**: :python:`True` |br|
|
|
*Maps to parameter*: -
|
|
|
|
OPERATIONS_SORTER
|
|
-----------------
|
|
|
|
Sorting order for the operation list of each tag.
|
|
|
|
* :python:`None`: show in the order returned by the server
|
|
* :python:`'alpha'`: sort alphabetically by path
|
|
* :python:`'method'`: sort by HTTP method
|
|
|
|
**Default**: :python:`None` |br|
|
|
*Maps to parameter*: ``operationsSorter``
|
|
|
|
TAGS_SORTER
|
|
-----------
|
|
|
|
Sorting order for tagged operation groups.
|
|
|
|
* :python:`None`: Swagger UI default ordering
|
|
* :python:`'alpha'`: sort alphabetically
|
|
|
|
**Default**: :python:`None` |br|
|
|
*Maps to parameter*: ``tagsSorter``
|
|
|
|
DOC_EXPANSION
|
|
-------------
|
|
|
|
Controls the default expansion setting for the operations and tags.
|
|
|
|
* :python:`'none'`: everything is collapsed
|
|
* :python:`'list'`: only tags are expanded
|
|
* :python:`'full'`: all operations are expanded
|
|
|
|
**Default**: :python:`'list'` |br|
|
|
*Maps to parameter*: ``docExpansion``
|
|
|
|
DEEP_LINKING
|
|
------------
|
|
|
|
Automatically update the fragment part of the URL with permalinks to the currently selected operation.
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to parameter*: ``deepLinking``
|
|
|
|
SHOW_EXTENSIONS
|
|
---------------
|
|
|
|
Show vendor extension (``x-..``) fields.
|
|
|
|
**Default**: :python:`True` |br|
|
|
*Maps to parameter*: ``showExtensions``
|
|
|
|
DEFAULT_MODEL_RENDERING
|
|
-----------------------
|
|
|
|
Controls whether operations show the model structure or the example value by default.
|
|
|
|
* :python:`'model'`: show the model fields by default
|
|
* :python:`'example'`: show the example value by default
|
|
|
|
**Default**: :python:`'model'` |br|
|
|
*Maps to parameter*: ``defaultModelRendering``
|
|
|
|
DEFAULT_MODEL_DEPTH
|
|
-------------------
|
|
|
|
Controls how many levels are expaned by default when showing nested models.
|
|
|
|
**Default**: :python:`3` |br|
|
|
*Maps to parameter*: ``defaultModelExpandDepth``
|
|
|
|
SHOW_COMMON_EXTENSIONS
|
|
----------------------
|
|
|
|
Controls the display of extensions (``pattern``, ``maxLength``, ``minLength``, ``maximum``, ``minimum``) fields and
|
|
values for Parameters.
|
|
|
|
**Default**: :python:`True` |br|
|
|
*Maps to parameter*: ``showCommonExtensions``
|
|
|
|
.. _oauth2-settings:
|
|
|
|
OAUTH2_REDIRECT_URL
|
|
-------------------
|
|
|
|
Used when OAuth2 authentication of API requests via swagger-ui is desired. If ``None`` is passed, the
|
|
``oauth2RedirectUrl`` parameter will be set to ``{% static 'drf-yasg/swagger-ui-dist/oauth2-redirect.html' %}``. This
|
|
is the default `https://github.com/swagger-api/swagger-ui/blob/master/dist/oauth2-redirect.html <oauth2-redirect>`_
|
|
file provided by ``swagger-ui``.
|
|
|
|
**Default**: :python:`None` |br|
|
|
*Maps to parameter*: ``oauth2RedirectUrl``
|
|
|
|
OAUTH2_CONFIG
|
|
-------------
|
|
|
|
Used when OAuth2 authentication of API requests via swagger-ui is desired. Provides OAuth2 configuration parameters
|
|
to the ``SwaggerUIBundle#initOAuth`` method, and must be a dictionary. See
|
|
`OAuth2 configuration <https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md>`_.
|
|
|
|
**Default**: :python:`{}`
|
|
|
|
SUPPORTED_SUBMIT_METHODS
|
|
------------------------
|
|
|
|
List of HTTP methods that have the Try it out feature enabled. An empty array disables Try it out for all operations.
|
|
This does not filter the operations from the display.
|
|
|
|
**Default**: :python:`['get','put','post','delete','options','head','patch','trace']` |br|
|
|
*Maps to parameter*: ``supportedSubmitMethods``
|
|
|
|
DISPLAY_OPERATION_ID
|
|
--------------------
|
|
|
|
Controls the display of operationId in operations list.
|
|
|
|
**Default**: :python:`True`
|
|
*Maps to parameter*: ``displayOperationId``
|
|
|
|
**************
|
|
REDOC_SETTINGS
|
|
**************
|
|
|
|
.. _redoc-ui-settings:
|
|
|
|
ReDoc UI settings
|
|
=================
|
|
|
|
ReDoc UI configuration settings. |br|
|
|
See https://github.com/Rebilly/ReDoc#configuration.
|
|
|
|
SPEC_URL
|
|
--------
|
|
|
|
URL pointing to a swagger document for use by ReDoc. The default behaviour is to append ``?format=openapi`` to the
|
|
URL which serves the UI; see :ref:`note on URL settings <url-settings>` above.
|
|
|
|
**Default**: :python:`None` |br|
|
|
*Maps to attribute*: ``spec-url``
|
|
|
|
LAZY_RENDERING
|
|
--------------
|
|
|
|
If set, enables lazy rendering mode in ReDoc. This mode is useful for APIs with big number of operations (e.g. > 50).
|
|
In this mode ReDoc shows initial screen ASAP and then renders the rest operations asynchronously while showing
|
|
progress bar on the top.
|
|
|
|
**NOTE:** this feature might be removed in future versions of ReDoc (see https://github.com/Rebilly/ReDoc/issues/475)
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to attribute*: ``lazyRendering``
|
|
|
|
HIDE_HOSTNAME
|
|
-------------
|
|
|
|
If set, the protocol and hostname is not shown in the operation definition.
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to attribute*: ``hideHostname``
|
|
|
|
EXPAND_RESPONSES
|
|
----------------
|
|
|
|
Specify which responses to expand by default by response codes. Values should be passed as comma-separated list without
|
|
spaces e.g. expandResponses="200,201". Special value "all" expands all responses by default.
|
|
Be careful: this option can slow-down documentation rendering time.
|
|
|
|
**Default**: :python:`'all'` |br|
|
|
*Maps to attribute*: ``expandResponses``
|
|
|
|
PATH_IN_MIDDLE
|
|
--------------
|
|
|
|
Show path link and HTTP verb in the middle panel instead of the right one.
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to attribute*: ``pathInMiddlePanel``
|
|
|
|
NATIVE_SCROLLBARS
|
|
-----------------
|
|
|
|
Use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to attribute*: ``nativeScrollbars``
|
|
|
|
REQUIRED_PROPS_FIRST
|
|
--------------------
|
|
|
|
Show required properties first ordered in the same order as in required array.
|
|
|
|
**Default**: :python:`False` |br|
|
|
*Maps to attribute*: ``requiredPropsFirst``
|
|
|
|
FETCH_SCHEMA_WITH_QUERY
|
|
-----------------------
|
|
|
|
Fetch the OpenAPI document using the query parameters passed to the ReDoc page request.
|
|
|
|
**Default**: :python:`True` |br|
|
|
*Maps to parameter*: -
|
|
|
|
|
|
.. _FORCE_SCRIPT_NAME: https://docs.djangoproject.com/en/2.0/ref/settings/#force-script-name
|