drf-yasg - Yet another Swagger generator

     

Generate real Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API.

Compatible with

• Django Rest Framework: 3.7.7, 3.8
• Django: 1.11, 2.0, 2.1
• Python: 2.7, 3.4, 3.5, 3.6, 3.7

Resources:

• Source: https://github.com/axnsan12/drf-yasg/
• Documentation: https://drf-yasg.readthedocs.io/
• Changelog: https://drf-yasg.readthedocs.io/en/stable/changelog.html
• Live demo: https://drf-yasg-demo.herokuapp.com/

Features

• full support for nested Serializers and Schemas
• response schemas and descriptions
• model definitions compatible with codegen tools
• customization hooks at all points in the spec generation process
• JSON and YAML format for spec
• bundles latest version of swagger-ui and redoc for viewing the generated documentation
• schema view is cacheable out of the box
• generated Swagger schema can be automatically validated by swagger-spec-validator or flex
• supports Django REST Framework API versioning with URLPathVersioning and NamespaceVersioning; other DRF or custom versioning schemes are not currently supported

Fully nested request and response schemas.

Choose between redoc and swagger-ui.

Real Model definitions.

Table of contents

Contents

• Features
• Table of contents
• Usage
  • 0. Installation
  • 1. Quickstart
  • 2. Configuration
    • a. get_schema_view parameters
    • b. SchemaView options
    • c. SWAGGER_SETTINGS and REDOC_SETTINGS
  • 3. Caching
  • 4. Validation
    • swagger-ui validation badge
      • Online
      • Offline
    • Using swagger-cli
    • Manually on editor.swagger.io
  • 5. Code generation
  • 6. Example project
• Background
  • Swagger in Django Rest Framework
  • Other libraries
• Third-party integrations
  • djangorestframework-camel-case
  • djangorestframework-recursive

Usage

0. Installation

The preferred instalation method is directly from pypi:

pip install -U drf-yasg

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[validation]

1. Quickstart

In settings.py:

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

In urls.py:

...
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="[email protected]"),
      license=openapi.License(name="BSD License"),
   ),
   validators=['flex', 'ssv'],
   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 cached, validated and publicly available 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

a. get_schema_view parameters

• info - Swagger API Info object; if omitted, defaults to DEFAULT_INFO
• url - API base url; if left blank will be deduced from the location the view is served at
• patterns - passed to SchemaGenerator
• urlconf - passed to SchemaGenerator
• public - if False, includes only endpoints the current user has access to
• validators - a list of validator names to apply on the generated schema; allowed values are flex, ssv
• generator_class - schema generator class to use; should be a subclass of OpenAPISchemaGenerator
• authentication_classes - authentication classes for the schema view itself
• permission_classes - permission classes for the schema view itself

b. SchemaView options

• SchemaView.with_ui(renderer, cache_timeout, cache_kwargs) - get a view instance using the specified UI renderer; one of swagger, redoc
• SchemaView.without_ui(cache_timeout, cache_kwargs) - get a view instance with no UI renderer; same as as_cached_view with no kwargs
• SchemaView.as_cached_view(cache_timeout, cache_kwargs, **initkwargs) - same as as_view, but with optional caching
• you can, of course, call as_view as usual

All of the first 3 methods take two optional arguments, cache_timeout and cache_kwargs; if present, these are passed on to Django’s cached_page decorator in order to enable caching on the resulting view. See 3. Caching.

c. SWAGGER_SETTINGS and REDOC_SETTINGS

Additionally, you can include some more settings in your settings.py file. See https://drf-yasg.readthedocs.io/en/stable/settings.html for details.

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 customzie 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=['flex', '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-ui validation badge

Online

If your schema is publicly accessible, swagger-ui will automatically validate it against the official swagger online validator and display the result in the bottom-right validation badge.

Offline

If your schema is not accessible from the internet, you can run a local copy of swagger-validator and set the VALIDATOR_URL accordingly:

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
{}

Using swagger-cli

https://www.npmjs.com/package/swagger-cli

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

Manually on editor.swagger.io

Importing the generated spec into https://editor.swagger.io/ will automatically trigger validation on it. This method is currently the only way to get both syntactic and semantic validation on your specification. The other validators only provide JSON schema-level validation, but miss things like duplicate operation names, improper content types, etc

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/axnsan12/drf-yasg.git
$ cd drf-yasg
$ virtualenv venv
$ source venv/bin/activate
(venv) $ cd testproj
(venv) $ pip install -U -r requirements.txt
(venv) $ python manage.py migrate
(venv) $ python manage.py shell -c "import createsuperuser"
(venv) $ python manage.py runserver
(venv) $ firefox localhost:8000/swagger/

Background

OpenAPI 2.0/Swagger is a format designed to encode information about a Web API into an easily parsable schema that can then be used for rendering documentation, generating code, etc.

More details are available on swagger.io and on the OpenAPI 2.0 specification page.

From here on, the terms “OpenAPI” and “Swagger” are used interchangeably.

Swagger in Django Rest Framework

Since Django Rest Framework 3.7, there is now built in support for automatic OpenAPI 2.0 schema generation. However, this generation is based on the coreapi standard, which for the moment is vastly inferior to OpenAPI in both features and tooling support. In particular, the OpenAPI codec/compatibility layer provided has a few major problems:

• there is no support for documenting response schemas and status codes
• nested schemas do not work properly
• does not handle more complex fields such as FileField, ChoiceField, …

In short this makes the generated schema unusable for code generation, and mediocre at best for documentation.

Other libraries

There are currently two decent Swagger schema generators that I could find for django-rest-framework:

• django-rest-swagger
• drf-openapi

django-rest-swagger is just a wrapper around DRF 3.7 schema generation with an added UI, and thus presents the same problems, while also being unmaintained. drf-openapi was discontinued by the author on April 3rd, 2018.

Third-party integrations

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.