0. Installation

The preferred instalation method is directly from pypi:

pip install -U drf-yasg-edge

Additionally, if you want to use the built-in validation mechanisms (see 4. Validation), you need to install some extra requirements:

pip install -U drf-yasg-edge[validation]

1. Quickstart

In settings.py:

INSTALLED_APPS = [
   ...
   'drf_yasg',
   ...
]

In urls.py:

...
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 = [
   url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   ...
]

This exposes 4 endpoints:

• A JSON view of your API specification at /swagger.json

• A YAML view of your API specification at /swagger.yaml

• A swagger-ui view of your API specification at /swagger/

• A ReDoc view of your API specification at /redoc/

2. Configuration

3. Caching

Since the schema does not usually change during the lifetime of the django process, there is out of the box support for caching the schema view in-memory, with some sane defaults:

• caching is enabled by the cache_page decorator, using the default Django cache backend, can be changed using the cache_kwargs argument

• HTTP caching of the response is blocked to avoid confusing situations caused by being shown stale schemas

• the cached schema varies on the Cookie and Authorization HTTP headers to enable filtering of visible endpoints according to the authentication credentials of each user; note that this means that every user accessing the schema will have a separate schema cached in memory.

4. Validation

Given the numerous methods to manually customize the generated schema, it makes sense to validate the result to ensure it still conforms to OpenAPI 2.0. To this end, validation is provided at the generation point using python swagger libraries, and can be activated by passing validators=['ssv'] to get_schema_view; if the generated schema is not valid, a SwaggerValidationError is raised by the handling codec.

Warning: This internal validation can slow down your server. Caching can mitigate the speed impact of validation.

The provided validation will catch syntactic errors, but more subtle violations of the spec might slip by them. To ensure compatibility with code generation tools, it is recommended to also employ one or more of the following methods:

SWAGGER_SETTINGS = {
    ...
    'VALIDATOR_URL': 'http://localhost:8189',
    ...
}

$ docker run --name swagger-validator -d -p 8189:8080 --add-host test.local:10.0.75.1 swaggerapi/swagger-validator
84dabd52ba967c32ae6b660934fa6a429ca6bc9e594d56e822a858b57039c8a2
$ curl http://localhost:8189/debug?url=http://test.local:8002/swagger/?format=openapi
{}

$ npm install -g swagger-cli
[...]
$ swagger-cli validate http://test.local:8002/swagger.yaml
http://test.local:8002/swagger.yaml is valid

5. Code generation

You can use the specification outputted by this library together with swagger-codegen to generate client code in your language of choice:

$ docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate -i /local/tests/reference.yaml -l javascript -o /local/.codegen/js

See the github page linked above for more details.

6. Example project

For additional usage examples, you can take a look at the test project in the testproj directory:

$ git clone https://github.com/banxi1988/drf-yasg.git
$ cd drf-yasg
$ virtualenv venv
$ source venv/bin/activate
(venv) $ cd testproj
(venv) $ python -m pip install -U pip setuptools
(venv) $ pip install -U -r requirements.txt
(venv) $ python manage.py migrate
(venv) $ python manage.py runserver
(venv) $ firefox localhost:8000/swagger/

djangorestframework-camel-case

Integration with djangorestframework-camel-case is provided out of the box - if you have djangorestframework-camel-case installed and your APIView uses CamelCaseJSONParser or CamelCaseJSONRenderer, all property names will be converted to camelCase by default.

djangorestframework-recursive

Integration with djangorestframework-recursive is provided out of the box - if you have djangorestframework-recursive installed.