Beautiful Django Rest Framework API documentation autogeneration through OpenAPI standard
Clone or download
Pull request Compare This branch is 20 commits behind limdauto:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
docs
drf_openapi
examples
images
tests
.editorconfig
.gitignore
.travis.yml
AUTHORS.rst
CONTRIBUTING.rst
HISTORY.rst
LICENSE
MANIFEST.in
Makefile
README.rst
requirements_dev.txt
setup.cfg
setup.py
tox.ini
travis_pypi_setup.py

README.rst

DRF OpenAPI

Documentation Status Updates Join the chat at https://gitter.im/drf_openapi/Lobby

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.

https://raw.githubusercontent.com/limdauto/drf_openapi/master/images/screenshot.png

1. 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.

2. Requirements:

This project was born to bridge the gap between DRF and OpenAPI. 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
  • Support multiple response codes, not just 200
  • 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.

3. Design

  • Schema are automatically generated from serializers
    • From here onwards, schema and serializer are used interchangably
  • Versioned schema is supported by extending VersionedSerializers.
  • Metadata, i.e. versioning, response and request schema, are bound to a view method through the view_config decorator.
  • Extra schema information such as response status codes and their descriptions are bound to the serializer Meta class
  • Automatic response validation is optionally provided view_config(response_serializer=FooSerializer, validate_response=True)

4. 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.

5. Examples

Please read the docs for a quickstart.

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

6. License

MIT