Settings are configurable in settings.py
by defining SWAGGER_SETTINGS
or REDOC_SETTINGS
.
Example:
settings.py
SWAGGER_SETTINGS = {
'SECURITY_DEFINITIONS': {
'basic': {
'type': 'basic'
}
},
...
}
REDOC_SETTINGS = {
'LAZY_RENDERING': False,
...
}
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:
: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`
: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`
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: [
:class:`'drf_yasg.inspectors.CamelCaseJSONFilter' <.inspectors.CamelCaseJSONFilter>`,
:class:`'drf_yasg.inspectors.ReferencingSerializerInspector' <.inspectors.ReferencingSerializerInspector>`,
:class:`'drf_yasg.inspectors.RelatedFieldInspector' <.inspectors.RelatedFieldInspector>`,
:class:`'drf_yasg.inspectors.ChoiceFieldInspector' <.inspectors.ChoiceFieldInspector>`,
:class:`'drf_yasg.inspectors.FileFieldInspector' <.inspectors.FileFieldInspector>`,
:class:`'drf_yasg.inspectors.DictFieldInspector' <.inspectors.DictFieldInspector>`,
:class:`'drf_yasg.inspectors.HiddenFieldInspector' <.inspectors.HiddenFieldInspector>`,
:class:`'drf_yasg.inspectors.RecursiveFieldInspector' <.inspectors.RecursiveFieldInspector>`,
:class:`'drf_yasg.inspectors.SerializerMethodFieldInspector' <.inspectors.SerializerMethodFieldInspector>`,
:class:`'drf_yasg.inspectors.SimpleFieldInspector' <.inspectors.SimpleFieldInspector>`,
:class:`'drf_yasg.inspectors.StringDefaultFieldInspector' <.inspectors.StringDefaultFieldInspector>`,
]
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: [
:class:`'drf_yasg.inspectors.CoreAPICompatInspector' <.inspectors.CoreAPICompatInspector>`,
]
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: [
:class:`'drf_yasg.inspectors.DjangoRestResponsePagination' <.inspectors.DjangoRestResponsePagination>`,
:class:`'drf_yasg.inspectors.CoreAPICompatInspector' <.inspectors.CoreAPICompatInspector>`,
]
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: ['html']
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: None
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: None
Enable/disable Django login as an authentication/authorization mechanism. If True, a login/logout button will be displayed in Swagger UI.
Default: True
URL for the Django Login action when using USE_SESSION_AUTH.
Default: django.conf.settings.LOGIN_URL
URL for the Django Logout action when using USE_SESSION_AUTH.
Default: django.conf.settings.LOGOUT_URL
Swagger security definitions to be included in the specification.
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-definitions-object.
Default:
'basic': {
'type': 'basic'
}
Global security requirements. If None
, all schemes in SECURITY_DEFINITIONS
are accepted.
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityRequirementObject.
Default: None
Swagger UI configuration settings.
See https://github.com/swagger-api/swagger-ui/blob/112bca906553a937ac67adc2e500bdeed96d067b/docs/usage/configuration.md#parameters.
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: None
Maps to parameter: 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 or
set to None
to remove the badge.
Default: 'http://online.swagger.io/validator/'
Maps to parameter: validatorUrl
Persist swagger-ui authorization data to local storage.
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: False
Maps to parameter: -
Re-fetch the OpenAPI document with the new credentials after authorization is performed through swagger-ui.
Default: False
Maps to parameter: -
Re-fetch the OpenAPI document without credentials after authorization is removed through swagger-ui.
Default: False
Maps to parameter: -
Fetch the OpenAPI document using the query parameters passed to the swagger-ui page request.
Default: True
Maps to parameter: -
Sorting order for the operation list of each tag.
None
: show in the order returned by the server'alpha'
: sort alphabetically by path'method'
: sort by HTTP method
Default: None
Maps to parameter: operationsSorter
Sorting order for tagged operation groups.
None
: Swagger UI default ordering'alpha'
: sort alphabetically
Default: None
Maps to parameter: tagsSorter
Controls the default expansion setting for the operations and tags.
'none'
: everything is collapsed'list'
: only tags are expanded'full'
: all operations are expanded
Default: 'list'
Maps to parameter: docExpansion
Automatically update the fragment part of the URL with permalinks to the currently selected operation.
Default: False
Maps to parameter: deepLinking
Show vendor extension (x-..
) fields.
Default: True
Maps to parameter: showExtensions
Controls whether operations show the model structure or the example value by default.
'model'
: show the model fields by default'example'
: show the example value by default
Default: 'model'
Maps to parameter: defaultModelRendering
Controls how many levels are expaned by default when showing nested models.
Default: 3
Maps to parameter: defaultModelExpandDepth
Controls the display of extensions (pattern
, maxLength
, minLength
, maximum
, minimum
) fields and
values for Parameters.
Default: True
Maps to parameter: showCommonExtensions
Used when OAuth2 authenitcation 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
file provided by swagger-ui
.
Default: None
Maps to parameter: oauth2RedirectUrl
Used when OAuth2 authenitcation 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.
Default: {}
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: ['get','put','post','delete','options','head','patch','trace']
Maps to parameter: supportedSubmitMethods
Controls the display of operationId in operations list.
Default: True
Maps to parameter: displayOperationId
ReDoc UI configuration settings.
See https://github.com/Rebilly/ReDoc#configuration.
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: None
Maps to attribute: spec-url
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 Redocly/redoc#475)
Default: False
Maps to attribute: lazyRendering
If set, the protocol and hostname is not shown in the operation definition.
Default: False
Maps to attribute: hideHostname
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: 'all'
Maps to attribute: expandResponses
Show path link and HTTP verb in the middle panel instead of the right one.
Default: False
Maps to attribute: pathInMiddlePanel
Use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).
Default: False
Maps to attribute: nativeScrollbars
Show required properties first ordered in the same order as in required array.
Default: False
Maps to attribute: requiredPropsFirst
Fetch the OpenAPI document using the query parameters passed to the ReDoc page request.
Default: 'True
Maps to parameter: -