# 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 overridden 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 overridden 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_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.JSONFieldInspector'`,
`'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'`,
`]`

#### DEFAULT_SPEC_RENDERERS

List of spec renderers classes which used for plain schema rendering.

Default: `[`
`'drf_yasg.renderers.SwaggerYAMLRenderer'`,
`'drf_yasg.renderers.SwaggerJSONRenderer'`,
`'drf_yasg.renderers.OpenAPIRenderer'`,
`]`

### 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: `'/accounts/logout/'`

#### 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 behavior 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 expanded 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 behavior 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: -