YAML Docstring

Docstring parser powered by YAML syntax

This parser allows you override some parts of automatic method inspection behaviours.

Example:

@api_view(["POST"])
def foo_view(request):
    """
    Your docs
    ---
    # YAML (must be separated by `---`)

    type:
      name:
        required: true
        type: string
      url:
        required: false
        type: url
      created_at:
        required: true
        type: string
        format: date-time

    serializer: .serializers.FooSerializer
    omit_serializer: false
    many: true

    parameters_strategy: merge
    omit_parameters:
        - path
    parameters:
        - name: name
          description: Foobar long description goes here
          required: true
          type: string
          paramType: form
        - name: other_foo
          paramType: query
        - name: other_bar
          paramType: query
        - name: avatar
          type: file

    responseMessages:
        - code: 401
          message: Not authenticated

    consumes:
        - application/json
        - application/xml
    produces:
        - application/json
        - application/xml
    """
    ...

parameters

Define parameters and their properties in docstrings:

parameters:
    - name: some_param
      description: Foobar long description goes here
      required: true
      type: integer
      paramType: form
    - name: other_foo
      paramType: query
    - name: avatar
      type: file

For the fields allowed in each parameter, see the Parameter Object fields and the Data Type Fields.

Exceptions: $ref is not currently supported.

parameters meta-fields

pytype

If you have a Django Rest Framework serializer that you would like to use to populate type you can specify it with pytype:

pytype: .serializers.FooSerializer

Overriding parameters

parameters_strategy

It is possible to override parameters discovered by method inspector by defining: parameters_strategy option to either merge or replace

To define different strategies for different paramType‘s use the following syntax:

parameters_strategy:
    form: replace
    query: merge

By default strategy is set to merge

omit_parameters

Sometimes the method inspector produces a list of parameters that you might not want to see in SWAGGER form. To handle this situation define paramTypes that should be omitted

omit_parameters:
    - form

Serializers

You can explicitly specify the serializer:

serializer: some.package.FooSerializer

serializer can take a relative path, or no path. Lookup begins in the module of the view:

serializer: .package.FooSerializer

serializer: FooSerializer

You can specify different serializers for request and response:

request_serializer: some.package.FooSerializer
response_serializer: some.package.BarSerializer

You can prevent django-rest-swagger from using any serializer:

omit_serializer: true

type

If your view does not use a serializer at all but instead outputs a simple data type such as JSON you may define a custom response object in the method signature as follows:

type:
  name:
    required: true
    type: string
  url:
    required: false
    type: url

many

In cases where an API response is a list of objects, it is possible to mark this to django-rest-swagger by overriding many to True.

many: true

This overrides the type returned to be an array of the resolved API type. ViewSet list methods do not require this definition, and are marked as many automatically.

responseMessages

To document error codes that your APIView might throw you can define them in responseMessages:

responseMessages:
    - code: 401
      message: Not authenticated
    - code: 403
      message: Insufficient rights to call this procedure

Media Types

To document supported media types as input or output you can define them as consumes and/or produces, respectively

consumes:
    - application/json
    - application/xml
produces:
    - application/json
    - application/xml

Different models for reading and writing operations

REST Framework does not output write_only fields in responses and also does not require read_only fields to be provided. It is worth to automatically register 2 separate models for reading and writing operations.

The discovered serializer will be registered with Write or Read prefix. Response Class will be automatically adjusted if serializer class was detected by method inspector.

You can also refer to these models in your parameters:

parameters:
    - name: CigarSerializer
      type: WriteCigarSerializer
      paramType: body

view_mocker

Specify a function to modify (or replace entirely) the view that django-rest-swagger uses to introspect serializer class.

django-rest-swagger passes this function a view object, and expects a view object to be returned, or None, in which case this bit of introspection is skipped.

class ViewMockerNeedingAPI(ListCreateAPIView):
    def get_serializer_class(self):
        if self.request.tacos == 'tasty':
            return CommentSerializer
        else:
            return QuerySerializer

    def post(self, request, *args, **kwargs):
        """
        ---
        view_mocker: my_view_mocker
        """
        return super(ViewMockerNeedingAPI, self).post(request, *args, **kwargs)
def my_view_mocker(view):
    view.request.tacos = 'tasty'
    return view