drf-yasg Documentation

The library generates OpenAPI 2.0 documents. The structure follows the official Swagger/OpenAPI 2.0 specification:

• Swagger Object: Root object containing info, schemes, securityDefinitions, paths, and definitions.
• Paths: A mapping of {path} to PathItem objects. Each PathItem contains operations keyed by HTTP method (e.g., GET, POST).
• Operation: Identified by (path, http_method). Contains parameters (query, header, form), responses (mapping of status codes to Response objects), operationId, and tags.
• Definitions: A mapping of named models ({ModelName}) to Schema objects.

Schema vs. Parameter

To set up drf-yasg, follow these two steps:

1. Update settings.py

Add drf_yasg and django.contrib.staticfiles to your INSTALLED_APPS. staticfiles is required to serve the Swagger UI CSS and JS files.

INSTALLED_APPS = [
    ...
    'django.contrib.staticfiles',
    'drf_yasg',
    ...
]

2. Update urls.py

Define a schema_view using get_schema_view and add the corresponding paths to your urlpatterns to expose JSON, YAML, Swagger UI, and ReDoc endpoints.

from django.urls import re_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="Snippets API",
        default_version='v1',
        description="Test description",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="contact@snippets.local"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,)
)

urlpatterns = [
    path('swagger.<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
    ...
]

You can configure swagger-ui to act as an OAuth2 client for testing "Try it out" requests. This requires both a SECURITY_DEFINITIONS entry of type oauth2 and an OAUTH2_CONFIG dictionary in SWAGGER_SETTINGS.

Note: If your OAuth2 provider requires an absolute redirect URL, you can override the default redirect path using the OAUTH2_REDIRECT_URL setting. The default is <origin>/static/drf-yasg/swagger2-ui-dist/oauth2-redirect.html.

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'
   },
}

The library automatically inspects your Django Rest Framework (DRF) setup to build the schema:

• Paths: Generated by exploring patterns in your urlconf. Only views inheriting from DRF's APIView are processed.
• Path Parameters: Extracted from URL template parameters. Types are guessed from the view's queryset and lookup_field.
• Query Parameters: Generated from the view's filter_backends and paginator.
• Request Body: Generated for POST, PUT, and PATCH methods using the view's serializer_class.
  • If the view uses multipart/form-data or application/x-www-form-urlencoded, the body is output as form parameters.
  • Otherwise, it is output as a single body parameter wrapping a Schema.
• Responses:
  • If responses are manually provided via @swagger_auto_schema, those are used.
  • Otherwise, a default success code is assumed (204 for DELETE, 201 for POST, 200 for others).
  • For list views or paginated views, the response schema is automatically wrapped in an array or paging structure.
• Descriptions: Picked up from docstrings and help_text attributes.