Extensible auto django rest framework api generator
Project description
# 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
### 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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
drf_autodocs-0.3.tar.gz
(106.5 kB
view hashes)
Built Distribution
drf_autodocs-0.3-py3-none-any.whl
(112.1 kB
view hashes)
Close
Hashes for drf_autodocs-0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5c9f95cc3a5b703bcc40f2f22517a9ab33bc69b4b1d4826bb24962ffadfe3137 |
|
MD5 | 1592d19df492c1b7a2abff4cbccad228 |
|
BLAKE2b-256 | df8ef7a23c7fb782208d96d2cdb08647468c799a7853a0ee0a5411041acf7511 |