marcgibbons/django-rest-swagger — pull request #60 by pySilver (2014-02-19 21:39:06+00:00)
Title: Docstring parser powered by YAML

This parser allows you override some parts of automatic method inspection behaviours which are not always correct. Also you may style your documentation with Markdown syntax.

See the following documents for more information about YAML and Swagger:
- https://github.com/wordnik/swagger-core/wiki
- http://www.yaml.org/spec/1.2/spec.html
- https://github.com/wordnik/swagger-codegen/wiki/Creating-Swagger-JSON-from-YAML-files

1. Control over parameters
============================================================================
Define parameters and its properties in docstrings:

parameters:
- name: some_param
description: Foobar long description goes here
required: true
allowMultiple: false
type: integer
paramType: form
minimum: 10
maximum: 100
- name: other_foo
paramType: query
- name: avatar
type: file

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`

Sometimes method inspector produces wrong list of parameters that
you might not won't to see in SWAGGER form. To handle this situation
define `paramTypes` that should be omitted
omit_parameters:
- form

2. Control over serializers
============================================================================
Once in a while you are using different serializers inside methods
but automatic method inspector cannot detect this. For that purpose there
is two explicit parameters that allows you to discard serializer detected
by method inspector OR replace it with another one

serializer: some.package.FooSerializer
omit_serializer: true

3. Custom Response Class
============================================================================
If your view is not using serializer at all but instead outputs simple
data type such as JSON you may define custom response object in method
signature like follows:

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

4. Response Messages (Error Codes)
============================================================================
If you'd like to share common response errors that your APIView might throw
you can define them in docstring using following format:

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

SAMPLE DOCSTRING:
============================================================================

---
# API Docs
# Note: YAML always starts with `---`

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

serializer: .serializers.FooSerializer
omit_serializer: false

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

responseMessages:
- code: 401
message: Not authenticated

I've also added URL grouping and Token authentication from other PR's (credits goes there).