drf-openapi 1.3.0

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

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

0.8.0 (2017-07-28)

• Some minor fixes to make sure it works on generic project

• Add examples

0.8.1 (2017-07-28)

• Fix bug when parsing empty docstring of the serializer

0.9.0 (2017-07-28)

• Rename base VersionedSerializer into VersionedSerializers

0.9.1 (2017-07-28)

• Fix import issue after renaming

0.9.3 (2017-08-05)

• Add support for different response status codes (Issue 27)

0.9.5 (2017-08-12)

• Add Python 2.7 compatibility (thanks tuffnatty)

• Add support for ModelViewSet (thanks tuffnatty)

0.9.6 (2017-08-12)

• Fix type display for child of ListSerializer/ListField (Issue 28)

0.9.7 (2017-09-12)

• Improve permission for schema view (Issue 31)

0.9.8 (2017-10-01)

• Turn schema view into a class-based view for easier customization

0.9.9 (2017-10-01)

• Another fix for ListSerializer/ListField (Issue 28)

1.0.1 (2017-12-14)

• Fix DRF 3.7 compatibility issue

• Added (werwty) as a maintainer

1.1.0 (2017-12-14)

• Fix viewset that doesn’t have pagination_class (Issue 84) and (Issue 92)

1.2.0 (2017-12-20)

• Make serializer_class optional (Issue 57)