# Django REST framework auto docs
### What is it
DRF Auto Docs is an extension of [drf-docs](https://github.com/manosim/django-rest-framework-docs).
In addition to [drf-docs](https://github.com/manosim/django-rest-framework-docs) features provides:

 * optional response fields(if input is different from output)
 * functional view input/output documentation
 * tree-like structure
 * preserves formatting(spaces & new lines) in docstrings
 * markdown in docstrings
 * choice field options rendering
 * fields' help_text (to specify SerializerMethodField output, for example)
 * read_only/required rendering
 * documents filter_backends
 * documents authentication_classes
 * documents permission_classes
 * document extra url params(GET params)
 * possibility to expand docstrings while keeping them short(docstring formatting)
 * smartly removes read-only fields from request serializer

### What isn't supported yet:

 * viewsets
 * possibility to try in browser
 * permission listing
 * auth classes
 * content types

### Why use this?

 * keeps project and documentation synchronized without any effort
 * fills those nasty gaps, that made django-rest-swagger/drf-docs unusable in practice



# Samples

### Whole structure:

![whole structure](http://joxi.net/LmGnYqhelBEWrl.jpg)

### Single node:

![single node](http://joxi.net/E2ppYWh9GvEW2Y.jpg)

### Choices:

![choices](http://joxi.net/12M5L7CMkgyb2J.jpg)

### Nested items:

![nested items](http://joxi.net/brRK3EhJOBZdm1.jpg)

### Help text:

![help text](http://joxi.net/n2YXyRsoekWNm6.jpg)

### Docstring formatting:

```python
@format_docstring(request_example, response_example=response_example)
class BookReadUpdateHandler(RetrieveUpdateAPIView):
    """
    Wow, this magic decorator allows us to:
        1) Keep clean & short docstring
        2) Insert additional data in it, like request/response examples

    Request: {}
    Response: {response_example}
    """
    serializer_class = BookUpdateSerializer
```

### Produces:

![help text](http://joxi.net/1A5GqQTnbkbRmE.jpg)


# Installation
In virtualenv:

    pip install drf_autodocs

In settings:

    INSTALLED_APPS = [
        ...
        'drf_autodocs',
        ...
    ]

In your urls:

    urlpatterns = [
        ...
        url(r'^', include('drf_autodocs.urls')),
    ]


That's already enough for swagger-like docs,
result available on

`localhost:8000/docs/`

If you want functional views support and some more features, read below.

# Usage

### Class-Based views
Say you have a view like this:
```python
class BookReadUpdateHandler(RetrieveUpdateAPIView):
    serializer_class = BookUpdateSerializer
    queryset = Book.objects.all()
```

And say this serializers' input is different from output:
```python
class BookUpdateSerializer(serializers.ModelSerializer):
    class Meta:
        fields = ('name', 'author')
        model = Book

    def to_representation(self, instance):
        return LibrarySerializer(instance.library)
```

Now to know what return format is, one must make a request.
This package simplifies it via:

`response_serializer_class = YourSerializer`

Now your view looks like:
```python
class BookReadUpdateHandler(RetrieveUpdateAPIView):
    """
    Shiny and nice docstring, which:
        1) allows formatting
        2) `allows markdown`
    """
    serializer_class = BookUpdateSerializer
    response_serializer_class = LibrarySerializer
    queryset = Book.objects.all()
```

### Function-based views

For functional views, decorate them with.

`drf_autodocs.decorators.document_serializer_classes`

Note that response_serializer_class is optional.

Now it should look like
```python
from drf_autodocs.decorators import document_serializer_classes

@document_serializer_classes(serializer_class=BookSerializer, response_serializer_class=LibrarySerializer)
@api_view(['GET', 'POST', 'DELETE'])
def hello_world(request):
    """
    Works for `functional` views too!
    Yeah, that thing rocks!
    """
    return Response('hello_world response')
```

### Help text

This package uses default field attribute `help_text`
So, to make it available in docs simply implement it in field of serializer

Example:

```python
has_books = serializers.SerializerMethodField(help_text='returns Bool')
```

### Docstring formatting

```python
from .request_response_examples import request_example, response_example
from drf_autodocs.decorators import format_docstring


@format_docstring(request_example, response_example=response_example)
class BookReadUpdateHandler(RetrieveUpdateAPIView):
    """
    Wow, this magic decorator allows us to:
        1) Keep clean & short docstring
        2) Insert additional data in it, like request/response examples

    Request: {}
    Response: {response_example}
    """
    serializer_class = BookUpdateSerializer
    response_serializer_class = LibrarySerializer
    queryset = Book.objects.all()
```


# Customization
To change application look & feel, override

`templates/drf_autodocs/index.html`


For additional parsers(if you want other structure than tree), inherit from

 `drf_autodocs.parser.BaseAPIParser`



### Supports
  - Python 3(Not tested on 2, though might work)
  - Django 1.8+
  - Django Rest Framework 3+


# Credits
Thanks to [django](http://djangoproject.com), [django-REST](http://www.django-rest-framework.org/) for their awesome work,
and [drf-docs](https://github.com/manosim/django-rest-framework-docs) for source of inspiration as well as some parts of code