drf-openapi 0.7.0

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

DRF OpenAPI

Utilities to generate OpenAPI-compatible schema from API made with Django Rest Framework. Also use ReDoc as default interface.

• Free software: MIT license

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

Motivation

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.

Usage

1. Quickstart

Out of the box, DRF OpenAPI inspects all of the endpoints reigstered with Django Rest Framework (DRF) and automatically generate documenation for them based on metadata provided by DRF and your serializer definitions. So no need to do anything, just plug it in:

# in settings.py
INSTALLED_APPS = [
    ...
    'drf_openapi'
]
# 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.

Features

1. Schema

• Add per method schema definition through inspecting serializers

• Add per serializer versioning

• Add capability to generate response schema on an endpoint.

2. OpenAPI codec

• Return response object as defined by the response schema

• Return multiple response status codes and messages. [TODO]

3. UI

• Support different OpenAPI UIs, not just Swagger. For example, ReDoc.

4. Utils

• A declarative machanism to provide more metadata for an API endpoint and therefore providing richer information for documentation generation.

History

0.1.0 (2017-07-01)

• First release on PyPI.