https://github.com/limdauto/drf_openapi

[DEPRECATED] Beautiful Django Rest Framework API documentation autogeneration through OpenAPI standard
https://github.com/limdauto/drf_openapi

Last synced: 23 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/limdauto/drf_openapi
• Owner: limdauto
• License: mit
• Archived: true
• Created: 2017-07-01T22:35:35.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2020-04-21T19:05:45.000Z (over 4 years ago)
• Last Synced: 2024-11-10T09:48:44.940Z (about 1 month ago)
• Language: Python
• Homepage: https://drf-openapi.readthedocs.io/en/latest/
• Size: 586 KB
• Stars: 190
• Watchers: 14
• Forks: 39
• Open Issues: 48
• Metadata Files:
  • Readme: README.rst
  • Changelog: HISTORY.rst
  • Contributing: CONTRIBUTING.rst
  • License: LICENSE

Awesome Lists containing this project

• starred-awesome - drf_openapi - Beautiful Django Rest Framework API documentation autogeneration through OpenAPI standard (Python)

README

        
===========

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

        

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

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

    * 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 `_ 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 ``_.

6. License

------------

MIT