Settings¶
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:
SWAGGER_SETTINGS¶
Default classes¶
DEFAULT_GENERATOR_CLASS¶
OpenAPISchemaGenerator
subclass that will be used by default for generating the final
Schema
object. Can be overriden by the generator_class
argument to get_schema_view()
.
DEFAULT_AUTO_SCHEMA_CLASS¶
ViewInspector
subclass that will be used by default for generating Operation
objects when iterating over endpoints. Can be overriden by using the auto_schema argument of
@swagger_auto_schema
or by a swagger_schema
attribute on the view class.
DEFAULT_FIELD_INSPECTORS¶
List of FieldInspector
subclasses that will be used by default for inspecting serializers and
serializer fields. Field inspectors given to @swagger_auto_schema
will be prepended
to this list.
Default: [
'drf_yasg.inspectors.CamelCaseJSONFilter'
,
'drf_yasg.inspectors.ReferencingSerializerInspector'
,
'drf_yasg.inspectors.RelatedFieldInspector'
,
'drf_yasg.inspectors.ChoiceFieldInspector'
,
'drf_yasg.inspectors.FileFieldInspector'
,
'drf_yasg.inspectors.DictFieldInspector'
,
'drf_yasg.inspectors.HiddenFieldInspector'
,
'drf_yasg.inspectors.RecursiveFieldInspector'
,
'drf_yasg.inspectors.SerializerMethodFieldInspector'
,
'drf_yasg.inspectors.SimpleFieldInspector'
,
'drf_yasg.inspectors.StringDefaultFieldInspector'
,
]
DEFAULT_FILTER_INSPECTORS¶
List of FilterInspector
subclasses that will be used by default for inspecting filter backends.
Filter inspectors given to @swagger_auto_schema
will be prepended to this list.
Default: [
'drf_yasg.inspectors.CoreAPICompatInspector'
,
]
DEFAULT_PAGINATOR_INSPECTORS¶
List of PaginatorInspector
subclasses that will be used by default for inspecting paginators.
Paginator inspectors given to @swagger_auto_schema
will be prepended to this list.
Default: [
'drf_yasg.inspectors.DjangoRestResponsePagination'
,
'drf_yasg.inspectors.CoreAPICompatInspector'
,
]
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: [‘html’]
DEFAULT_INFO¶
An import string to an openapi.Info
object. This will be used when running the generate_swagger
management command, or if no info
argument is passed to get_schema_view()
.
Default: 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: documentation on base URL construction
Default: 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: True
LOGIN_URL¶
URL for the Django Login action when using USE_SESSION_AUTH.
Default: django.conf.settings.LOGIN_URL
LOGOUT_URL¶
URL for the Django Logout action when using USE_SESSION_AUTH.
Default: django.conf.settings.LOGOUT_URL
SECURITY_DEFINITIONS¶
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'
}
SECURITY_REQUIREMENTS¶
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 settings¶
Swagger UI configuration settings.
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 note on URL settings above.
Default: None
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 or
set to None
to remove the badge.
Default: ‘http://online.swagger.io/validator/’
Maps to parameter: validatorUrl
PERSIST_AUTH¶
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: -
REFETCH_SCHEMA_WITH_AUTH¶
Re-fetch the OpenAPI document with the new credentials after authorization is performed through swagger-ui.
Default: False
Maps to parameter: -
REFETCH_SCHEMA_ON_LOGOUT¶
Re-fetch the OpenAPI document without credentials after authorization is removed through swagger-ui.
Default: False
Maps to parameter: -
FETCH_SCHEMA_WITH_QUERY¶
Fetch the OpenAPI document using the query parameters passed to the swagger-ui page request.
Default: True
Maps to parameter: -
OPERATIONS_SORTER¶
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
TAGS_SORTER¶
Sorting order for tagged operation groups.
None
: Swagger UI default ordering‘alpha’
: sort alphabetically
Default: None
Maps to parameter: tagsSorter
DOC_EXPANSION¶
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
DEEP_LINKING¶
Automatically update the fragment part of the URL with permalinks to the currently selected operation.
Default: False
Maps to parameter: deepLinking
SHOW_EXTENSIONS¶
Show vendor extension (x-..
) fields.
Default: True
Maps to parameter: showExtensions
DEFAULT_MODEL_RENDERING¶
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
DEFAULT_MODEL_DEPTH¶
Controls how many levels are expaned by default when showing nested models.
Default: 3
Maps to parameter: defaultModelExpandDepth
SHOW_COMMON_EXTENSIONS¶
Controls the display of extensions (pattern
, maxLength
, minLength
, maximum
, minimum
) fields and
values for Parameters.
Default: True
Maps to parameter: showCommonExtensions
OAUTH2_REDIRECT_URL¶
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
OAUTH2_CONFIG¶
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: {}
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: [‘get’,’put’,’post’,’delete’,’options’,’head’,’patch’,’trace’]
Maps to parameter: supportedSubmitMethods
DISPLAY_OPERATION_ID¶
Controls the display of operationId in operations list.
Default: True
Maps to parameter: displayOperationId
REDOC_SETTINGS¶
ReDoc UI settings¶
ReDoc UI configuration settings.
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 note on URL settings above.
Default: None
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: False
Maps to attribute: lazyRendering
HIDE_HOSTNAME¶
If set, the protocol and hostname is not shown in the operation definition.
Default: False
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: ‘all’
Maps to attribute: expandResponses
PATH_IN_MIDDLE¶
Show path link and HTTP verb in the middle panel instead of the right one.
Default: False
Maps to attribute: pathInMiddlePanel
NATIVE_SCROLLBARS¶
Use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).
Default: False
Maps to attribute: nativeScrollbars
REQUIRED_PROPS_FIRST¶
Show required properties first ordered in the same order as in required array.
Default: False
Maps to attribute: requiredPropsFirst
FETCH_SCHEMA_WITH_QUERY¶
Fetch the OpenAPI document using the query parameters passed to the ReDoc page request.
Default: ‘True
Maps to parameter: -