Skip to main content

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

Project description

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

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

3. 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)`

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

5. 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/>`_.

6. 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>`_)


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

drf_openapi-1.3.0.tar.gz (22.3 kB view details)

Uploaded Source

Built Distribution

drf_openapi-1.3.0-py2.py3-none-any.whl (16.2 kB view details)

Uploaded Python 2Python 3

File details

Details for the file drf_openapi-1.3.0.tar.gz.

File metadata

  • Download URL: drf_openapi-1.3.0.tar.gz
  • Upload date:
  • Size: 22.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for drf_openapi-1.3.0.tar.gz
Algorithm Hash digest
SHA256 1cd1164ac6262252cb629df4de2c1a3f9a738e608ec9b56f26545d45ed673c1f
MD5 3ea15ac803070ea7d298cafd9c0ca1b7
BLAKE2b-256 d162272f29af7e2bf38fe92897abf57f49c9674b5d3b1f9a1683a953c59b9859

See more details on using hashes here.

File details

Details for the file drf_openapi-1.3.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for drf_openapi-1.3.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 21d28a0ea5b78243ee1b815041f715c1a7e9d60c063cbf9db5e4fa5535361460
MD5 c521c470fc8a31eeacad32a05dfdb510
BLAKE2b-256 2e5d35c9e1377461a83c798121e8fab3f920478010cd66026afce39a33fe28e7

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page