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: drf_yasg.generators.OpenAPISchemaGenerator

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: drf_yasg.inspectors.SwaggerAutoSchema

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 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 file provided by swagger-ui.

Default: None
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.

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: -