# restframework-schemagenerator


REST Framework SchemaGenerator is a instrospection tool that generates an
OpenAPI (*Swagger*) schema.

## Quickstart

$ pip install restframework_schemagenerator django-rest-swagger

In urls.py

urlpatterns = [
#...
url(r'^api/v1/$', include('restframework_schemagenerator.urls')),
]

## Swagger UI

django-rest-swagger is not required by restframework-schemagenerator, but if it
is installed, the SchemaView will use it as a renderer.

## Customization

By default, restframework_schemagenerator inspects the whole ROOT\_URLCONF. This is customizable by
not using ``restframework_schemagenerator.urls`` but using ``restframework_schemagenerator.views.SchemaView`` and settings
``urlconf`` and ``prefix`` in the as\_view() method.

from restframework_schemagenerator.views import SchemaView
urlpatterns = [
#...
url(r'^api/v1/', include('project.api_v1_urls')),
url(r'^api/v1/$', SchemaView.as_view(
title='API V1 documentation',
prefix='/api/v1/',
urlconf='project.api_v1_urls',
)
]


## Introspection

The schema generation uses introspection of the views and the serializers to
create its representation of the API. The introspection automatically detects:

- The body of the request and responses of viewsets from the ``serializer_class``
- The description of API views method (get, put, ...) and the description of
API viewsets actions (retrieve, update, ...)
- The URL parameters
- The expected and produced content types from the parsers and renderers.

The introspection does not detect

- The authentication mechanism
- The GET parameters
- The consumed and produced headers
- API views that are not subclasses of ``rest_framework.views.APIView`` or
``rest_framework.viewsets.ViewSet``

### Override API intropsection

It can be overriden by a class Schema at the root of the APIView or ViewSet

class MyViewSet(ViewSet):
class Schema:
post = {
'description': 'This endpoint creates a new resource',
}

#### Parameter

The parameter coming from the URL can be described with a class Parameter
inside the Schema class. The description can provide a description and a type.


class MyViewSet(ViewSet):
class Schema:
class Parameter:
pk = {
'description': 'The unique ID of the object',
}


#### Response

Response can be overriden in two ways.

When there is a single response expected, the response dict is merged with the
automatically generated response.

class MyViewSet(ViewSet):
def create(self, request, *args, **kw):
pass

class Schema:
create = {
'response': {
'description': 'This endpoint creates a new resource',
}
}


When there is a list of responses the response are copied verbatim and nothing
is generated automatically.

class MyViewSet(GenericAPIView):
def put(self, request, *args, **kw):
pass

class Schema:
put = {
'responses': [{
'status': 200,
'description': 'The resource was found',
'output': MySerializer(),
}, {
'status': 201,
'description': 'The resource was create',
'output': MySerializer(),
}],
}


Render warnings:
<string>:16: (WARNING/2) Definition list ends without a blank line; unexpected unindent.