django-rest-coreapi-schema 0.1.2
Django restframework custom schema
Keywords: django restframework schema coreapi swagger

Django restframework schema
===========================

This package is a schema for django restframework.

How to use
==========

Installation
------------

.. code:: bash

    $ pip install django-rest-coreapi-schema

.. code:: bash

    $ pip install -e git+https://github.com/emilioag/django_rest_coreapi_schema.git#egg=django_rest_coreapi_schema

Configuration
-------------

django settings
~~~~~~~~~~~~~~~

Add the next configuration in your settings.py file.

.. code:: python

    REST_FRAMEWORK = {
        'DEFAULT_SCHEMA_CLASS': 'django_rest_coreapi_schema.schema.CoreAPIAutoSchema',
    }

Restframework docs (urls)
~~~~~~~~~~~~~~~~~~~~~~~~~

Add to your urls.py the restframework docs

.. code:: python

    from django.conf.urls import url
    from rest_framework.documentation import include_docs_urls

    urlpatterns = [
        url(r'^docs/', include_docs_urls(title='My API title', description='API description', public=False)),
    ]

Create your serializers
~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    from rest_framework import serializers


    class UserSerializer(serializers.Serializer):
        email = serializers.CharField(
            required=False,
            help_text="User email")
        address = serializers.CharField(
            required=False,
            help_text="User address")


    class FilterSerializer(serializers.Serializer):
        order = serializers.ChoiceField(
            required=False,
            choices=[("asc", "Asc"), ("desc", "desc")],
            help_text="Order")
        username = serializers.CharField(
            required=False,
            help_text="Username pattern")


    class PathSerializer(serializers.Serializer):
        username = serializers.CharField(
            required=True,
            help_text="Username")

Create your pagination
~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    from rest_framework.pagination import PageNumberPagination


    class LargeResultsSetPagination(PageNumberPagination):
        page_size = 1000
        page_size_query_param = 'page_size'
        max_page_size = 10000

Create your view
----------------

Documenting path variables
~~~~~~~~~~~~~~~~~~~~~~~~~~

You have to use the class variable: ``queryset``

.. code:: python

    from django_rest_coreapi_schema.views import DocumentedBaseView

    class UserView(DocumentedBaseView):
        queryset = PathSerializer

Url args
~~~~~~~~

You have to use the class variables: ``filter_backends`` and
``filter_fields``

-  **filter\_backends** is a list of serializers which contains all the
   possible url args.
-  **filter\_fields** is a list of arg names that will be appear in the
   coreapi documentation.

.. code:: python

    from django_rest_coreapi_schema.views import DocumentedBaseView

    class UserListView(DocumentedBaseView):
        filter_backends = [FilterSerializer]
        filter_fields = ('order', 'username')

Body
~~~~

Http put, post, etc. body.

.. code:: python

    from django_rest_coreapi_schema.views import DocumentedBaseView

    class UserView(DocumentedBaseView):
        body_serializer_class = UserSerializer

Pagination (for large results)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    from django_rest_coreapi_schema.views import DocumentedBaseView

    class UserListView(DocumentedBaseView):
        pagination_class = LargeResultsSetPagination

You can see a whole example in examples/restAPI folder inside this
repository.