Skip to content
This repository has been archived by the owner. It is now read-only.
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.rst

DRF OpenAPI

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

DEPRECATION NOTICE This project is deprecated in favour of https://github.com/axnsan12/drf-yasg/ or if you can wait https://github.com/encode/django-rest-framework/commit/e5781440fa6ccff09abc6e0566bdfdd9b84a80a1 :) :) :)

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

About

[DEPRECATED] Beautiful Django Rest Framework API documentation autogeneration through OpenAPI standard

Resources

License

Packages

No packages published