Describing authentication schemes

When using the swagger-ui frontend, it is possible to interact with the API described by your Swagger document. This interaction might require authentication, which you will have to describe in order to make swagger-ui work with it.

Security definitions

The first step that you have to do is add a SECURITY_DEFINITIONS setting to declare all authentication schemes supported by your API.

For example, the definition for a simple API accepting HTTP basic auth and Authorization header API tokens would be:

SWAGGER_SETTINGS = {
   'SECURITY_DEFINITIONS': {
      'Basic': {
            'type': 'basic'
      },
      'Bearer': {
            'type': 'apiKey',
            'name': 'Authorization',
            'in': 'header'
      }
   }
}

Security requirements

The second step is specifying, for each endpoint, which authentication mechanism can be used for interacting with it. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-requirement-object for details.

By default, a top-level security that accepts any one of the declared security definitions is generated. For the example above, that would be [{'Basic': []}, {'Bearer': []}]. This can be overriden using the SECURITY_REQUIREMENTS setting.

Operation-level overrides can be added using the security parameter of @swagger_auto_schema.

swagger-ui as OAuth2 client

It is possible to configure swagger-ui to authenticate against your (or a third party) OAuth2 service when sending “Try it out” requests. This client-side configuration does not remove the requirement of a spec-side security definiiton, but merely allows you to test OAuth2 APIs using swagger-ui as a client.

DISCLAIMER: this setup is very poorly tested as I do not currently implement OAuth in any of my projects. All contributions relating to documentation, bugs, mistakes or anything else are welcome as an issue or pull request. The settings described below were added as a result of discussion in issue #53.

The settings of interest can be found on the settings page. Configuration options are similar to most OAuth client setups like web or mobile applications. Reading the relevant swagger-ui docmentation linked will also probably help.

Example

A very simple working configuration was provided by @Vigrond, originally at https://github.com/Vigrond/django_oauth2_example.

SWAGGER_SETTINGS = {
   'USE_SESSION_AUTH': False,
   'SECURITY_DEFINITIONS': {
      'Your App API - Swagger': {
         'type': 'oauth2',
         'authorizationUrl': '/yourapp/o/authorize',
         'tokenUrl': '/yourapp/o/token/',
         'flow': 'accessCode',
         'scopes': {
          'read:groups': 'read groups',
         }
      }
   },
   'OAUTH2_CONFIG': {
      'clientId': 'yourAppClientId',
      'clientSecret': 'yourAppClientSecret',
      'appName': 'your application name'
   },
}

If the OAuth2 provider requires you to provide the full absolute redirect URL, the default value for most staticfiles configurations will be <origin>/static/drf-yasg/swagger-ui-dist/oauth2-redirect.html. If this is not suitable for some reason, you can override the OAUTH2_REDIRECT_URL setting as appropriate.