Django-rest-swagger: how can I specify the type of a parameter in docstring

Question

I am using django-rest-framwork and django-rest-swagger.

The problem is that I am retrieving data directly from the request body:

def put(self, request, format=None): """ This text is the description for this API username -- username password -- password """ username = request.DATA['username'] password = request.DATA['password'] 

but when I try to execute a request from swagger-ui, I cannot specify the “parameter type” (this is the default request and cannot find a way to change it from docstring)

I managed to get around my problem by changing some line in the build_query_params_from_docstring function from the introspectors.py file, but I was wondering if there was another way to do this.

Answer 1

UPDATE: this answer only works for django-rest-swagger <2, see comment from @krd below.

Docs: http://django-rest-swagger.readthedocs.org/en/latest/yaml.html

If you want to put the form data:

 def put(self, request, format=None): """ This text is the description for this API. --- parameters: - name: username description: Foobar long description goes here required: true type: string paramType: form - name: password paramType: form required: true type: string """ username = request.DATA['username'] password = request.DATA['password'] 

For the JSON body, you can do something like:

 def put(...): """ ... --- parameters: - name: body description: JSON object containing two strings: password and username. required: true paramType: body pytype: RequestSerializer """ ... 

Answer 2

Define the filter class in your view. django-rest no longer does this yaml stuff for parameters. The fields that you define in your filter class will appear as fields in the openapi / swagger documentation. It is very neat.

Read the full documentation.

http://www.django-rest-framework.org/apiguide/filtering/#djangofilterbackend

 from django_filters.rest_framework.filterset import FilterSet class ProductFilter(FilterSet): class Meta(object): models = models.Product fields = ( 'name', 'category', 'id', ) class PurchasedProductsList(generics.ListAPIView): """ Return a list of all the products that the authenticated user has ever purchased, with optional filtering. """ model = Product serializer_class = ProductSerializer filter_class = ProductFilter def get_queryset(self): user = self.request.user return user.purchase_set.all() 

fields defined in filtereet will be displayed in the documentation. but there will be no description.

Answer 3

Like John Van Buskirk, answer, here is what I have:

Actual manual document created:

drf_api / business / schema.py

 # encoding: utf-8 from __future__ import unicode_literals from __future__ import absolute_import import coreapi schema = coreapi.Document( title='Business Search API', url='/api/v3/business/', content={ 'search': coreapi.Link( url='/', action='get', fields=[ coreapi.Field( name='what', required=True, location='query', description='Search term' ), coreapi.Field( name='where', required=True, location='query', description='Search location' ), ], description='Search business listings' ) } ) 

Then we copied the get_swagger_view function and configured it:

drf_api / swagger.py

 # encoding: utf-8 from __future__ import unicode_literals from __future__ import absolute_import from rest_framework import exceptions from rest_framework.permissions import AllowAny from rest_framework.renderers import CoreJSONRenderer from rest_framework.response import Response from rest_framework.views import APIView from rest_framework_swagger import renderers from django.utils.module_loading import import_string def get_swagger_view(schema_location): """ Returns schema view which renders Swagger/OpenAPI. """ class SwaggerSchemaView(APIView): _ignore_model_permissions = True exclude_from_schema = True permission_classes = [AllowAny] renderer_classes = [ CoreJSONRenderer, renderers.OpenAPIRenderer, renderers.SwaggerUIRenderer ] def get(self, request): schema = None try: schema = import_string(schema_location) except: pass if not schema: raise exceptions.ValidationError( 'The schema generator did not return a schema Document' ) return Response(schema) return SwaggerSchemaView.as_view() 

Then connect it to urls.py

 from ..swagger import get_swagger_view from . import views schema_view = get_swagger_view(schema_location='drf_api.business.schema.schema') urlpatterns = [ url(r'^swagger/$', schema_view), 

Answer 4

The only way to succeed in defining parameter types is to create a view that defines what I want without using a generator.

 class SwaggerSchemaView(APIView): permission_classes = [IsAuthenticatedOrReadOnly,] renderer_classes = [renderers.OpenAPIRenderer, renderers.SwaggerUIRenderer] schema = coreapi.Document( title='Thingy API thing', 'range': coreapi.Link( url='/range/{start}/{end}', action='get', fields=[ coreapi.Field( name='start', required=True, location='path', description='start time as an epoch', type='integer' ), coreapi.Field( name='end', required=True, location='path', description='end time as an epoch', type='integer' ) ], description='show the things between the things' ), } ) 

and then using this class in urls.py

 urlpatterns = [ url(r'^$', SwaggerSchemaView.as_view()), ... ] 

Answer 5

FOR REGISTRATION DJANGO REST SWAGGER> 2.0: override the default DRF scheme generator, this document explains step by step integration of django rest swagger 2: full documentation of Django Rest Swagger 2