drf-openapi

=========== DRF OpenAPI

.. image:: https://img.shields.io/pypi/v/drf_openapi.svg :target: https://pypi.python.org/pypi/drf_openapi

.. image:: https://img.shields.io/travis/limdauto/drf_openapi.svg :target: https://travis-ci.org/limdauto/drf_openapi

.. image:: https://readthedocs.org/projects/drf-openapi/badge/?version=latest :target: https://drf-openapi.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

.. image:: https://pyup.io/repos/github/limdauto/drf_openapi/shield.svg :target: https://pyup.io/repos/github/limdauto/drf_openapi/ :alt: Updates

.. image:: https://badges.gitter.im/drf_openapi/Lobby.svg :target: https://gitter.im/drf_openapi/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge :alt: Join the chat at https://gitter.im/drf_openapi/Lobby

Generates OpenAPI-compatible schema from API made with Django Rest Framework. Use ReDoc <https://github.com/Rebilly/ReDoc>_ as default interface instead of Swagger. First-class support for API versioning changelog & method-specific schema definition.

.. figure:: https://raw.githubusercontent.com/limdauto/drf_openapi/master/images/screenshot.png :scale: 80%

.. contents::

1. Background

---

Django Rest Framework has an API schema generation/declaration mechanism <http://www.django-rest-framework.org/api-guide/schemas/>_ provided by coreapi <http://www.coreapi.org/>_ standard. There are a couple of problems with the current ecosystem:

• CoreAPI is not compatible out of the box with OpenAPI <https://www.openapis.org/>_ 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.

1. 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. :code:>1.0, <=2.0
• Support multiple response codes, not just :code: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.

1. Design

---

• Schema are automatically generated from serializers <http://www.django-rest-framework.org/api-guide/serializers/>_
  • From here onwards, :code:schema and :code:serializer are used interchangably
• Versioned schema is supported by extending :code:VersionedSerializers.
• Metadata, i.e. versioning, response and request schema, are bound to a view method through the :code:view_config decorator.
• Extra schema information such as response status codes and their descriptions are bound to the serializer :code:Meta class
• Automatic response validation is optionally provided :code:view_config(response_serializer=FooSerializer, validate_response=True)

1. Constraints

---

Currently DRF OpenAPI only supports DRF project that has versioning <http://www.django-rest-framework.org/api-guide/versioning/#urlpathversioning>_ enabled. I have only tested URLPathVersioning <http://www.django-rest-framework.org/api-guide/versioning/#urlpathversioning>_ but I intend to suppor the full range of versioning scheme supported by DRF.

1. Examples

---

Please read the docs <https://drf-openapi.readthedocs.io>_ for a quickstart.

Also I have recreated the example in DRF tutorial <http://www.django-rest-framework.org/tutorial/quickstart/>_ with OpenAPI schema enabled in <examples/>_.

1. License

---

MIT

======= History

0.1.0 (2017-07-01)

• First release on PyPI.

0.7.0 (2017-07-28)

• Implement :code:VersionedSerializer
• Implement :code: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 :code:VersionedSerializer into :code: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 <https://github.com/limdauto/drf_openapi/issues/27>_)

0.9.5 (2017-08-12)

• Add Python 2.7 compatibility (thanks tuffnatty <https://github.com/limdauto/drf_openapi/pull/35>_)
• Add support for ModelViewSet (thanks tuffnatty <https://github.com/limdauto/drf_openapi/pull/36>_)

0.9.6 (2017-08-12)

• Fix type display for child of ListSerializer/ListField (Issue 28 <https://github.com/limdauto/drf_openapi/issues/28>_)

0.9.7 (2017-09-12)

• Improve permission for schema view (Issue 31 <https://github.com/limdauto/drf_openapi/issues/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 <https://github.com/limdauto/drf_openapi/issues/28>_)

1.0.1 (2017-12-14)

• Fix DRF 3.7 compatibility issue
• Added (werwty <https://github.com/werwty>_) as a maintainer

1.1.0 (2017-12-14)

• Fix viewset that doesn't have pagination_class (Issue 84 <https://github.com/limdauto/drf_openapi/issues/84>) and (Issue 92 <https://github.com/limdauto/drf_openapi/issues/92>)

1.2.0 (2017-12-20)

• Make serializer_class optional (Issue 57 <https://github.com/limdauto/drf_openapi/issues/57>_)