drf-openapi 0.8.0

Utilities to generate OpenAPI-compatible schema from API made with Django Rest Framework

DRF OpenAPI

Generates OpenAPI-compatible schema from API made with Django Rest Framework. Use ReDoc as default interface instead of Swagger. First-class support for API versioning changelog & method-specific schema definition.

• Free software: MIT license

• Documentation: https://drf-openapi.readthedocs.io.

Contents

• DRF OpenAPI

  • Background

  • Design

  • Constraints

  • Installation

  • Usage

    • 1. Quickstart

    • 2. Add schema to a view method

    • 3. Add version to schema

  • Examples

• History

  • 0.1.0 (2017-07-01)

  • 0.7.0 (2017-07-28)

Background

Django Rest Framework has an API schema generation/declaration mechanism provided by coreapi standard. There are a couple of problems with the current ecosystem:

• CoreAPI is not compatible out of the box with OpenAPI which is a much more popular API standard with superior tooling support, i.e. Swagger et. al.

• The OpenAPI codec (compatibility layer) that CoreAPI team provides drops / doesn’t support a number of useful OpenAPI features.

• There is no support for versioning or method-specific schema.

This project was born to bridge the gap. The high-level requirements are as followed:

• Can be dropped into any existing DRF project without any code change necessary.

• Provide clear disctinction between request schema and response schema.

• Provide a versioning mechanism for each schema. Support defining schema by version range syntax, e.g. >1.0, <=2.0

• All this information should be bound to view methods, not view classes.

It’s important to stress the non-intrusiveness requirement, not least because I want to minimize what I will have to change when DRF itself decides to support OpenAPI officially, if at all.

Design

• Schema are automatically generated from serializers

  • From here onwards, schema and serializer are used interchangably

• Versioned schema is supported by extending VersionedSerializer.

• Metadata, i.e. versioning, response and request schema, are bound to a view method through the view_config decorator.

• Automatic response validation is optionally provided view_config(response_serializer=FooSerializer, validate_response=True)

Constraints

Currently DRF OpenAPI only supports DRF project that has versioning enabled. I have only tested URLPathVersioning but I intend to suppor the full range of versioning scheme supported by DRF.

Also the schema view is limited to staff member for now. I plan to add more granular permission very soon.

Installation

pip install drf_openapi

Usage

1. Quickstart

# in settings.py
INSTALLED_APPS = [
    ...
    'drf_openapi'
]
REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning'
}

# in urls.py
urlpatterns += [url(f'{API_PREFIX}/', include('drf_openapi.urls'))]

And voila! Your API documentation will be available at /<API_PREFIX>/schema

2. Add schema to a view method

DRF OpenAPI support the separation of response schema and request schema on a per view method basis through the use of a view_config decorator

from drf_openapi.utils import view_config

class MeEndpointSet(viewsets.ViewSet):

   @view_config(
       request_serializer=MeRequestSerializer,
       response_serializer=MeResponseSerializer,
       validate_response=True)
   def list(self, request, version) -> Response:
       # the serializers are available on the self object
       assert self.request_serializer == MeRequestSerializer
       assert self.response_serializer == MeResponseSerializer

3. Add version to schema

DRF OpenAPI support schema versioning through versioning the serializers that the schema are generated from. To make a serializer version-specific, extends VersionedSerializer

from drf_openapi.entities import VersionedSerializer
from rest_framework import serializers

class MeResponseSerializer(VersionedSerializer):
    class V1(serializers.Serializer):
        avatar = serializers.CharField(allowed_null=True)

    class V2(serialiers.Serializer):
        avatar =  serializers.CharField(allowed_null=False)

    VERSION_MAP = (
        '>=1.0, <2.0': V1,
        '>=2.0': V2
    )

That’s it. The view_config decorator will be able to correctly determined what serializer to use based on the request version at run time.

Examples

I have recreated the example in DRF tutorial with OpenAPI schema enabled in examples.

History

0.1.0 (2017-07-01)

• First release on PyPI.

0.7.0 (2017-07-28)

• Implement VersionedSerializer

• Implement view_config

• Make the library an installable Django app