Improve nested serializer in API documentation

[jpadilla]

Steps to reproduce

class ASerializer(serializers.Serializer):
    name = serializers.CharField()


class BSerializer(serializers.Serializer):
    name = serializers.CharField()
    animal = ASerializer()

Expected behavior

Expose parameters from nested serializers. A custom docs/link.html template allowed me to expose at least one level pretty easy by doing:

{% for field in link.fields|with_location:'form' %}
<tr>
  <td class="parameter-name"><code>{{ field.name }}</code>{% if field.required %} <span class="label label-warning">required</span>{% endif %}</td><td>{% if field.schema.description %}{{ field.schema.description }}{% endif %}</td>
  {% if field.schema.properties %}
    {% for name, nested_field in field.schema.properties.iteritems %}
      <tr><td class="parameter-name" style="padding-left: 25px;"><code>{{ name }}</code>{% if nested_field.required %} <span class="label label-warning">required</span>{% endif %}</td><td>{% if nested_field.schema.description %}{{ nested_field.schema.description }}{% endif %}</td></tr>
    {% endfor %}
  {% endif %}
</tr>
{% endfor %}

Stripe's API Reference handles this pretty nice and I think is something we could look up to for reference.

Actual behavior

[tomchristie]

Yup, agreed.

[jpadilla]

@tomchristie I'll be taking a stab at a first iteration in the next couple of days. Have also been thinking about how we could also improve the actual interact form, right now you get a textarea with a {}. Might be interesting to treat nested serializer as a form group there as well. Thoughts?

[tomchristie]

Might be interesting to treat nested serializer as a form group there as well.

100% yes. Awkward, in the same way that it's awkward for us to do nested forms in the browsable API, but at least in this case we'd be marshalling it into JSON by the time we're actually making the request.

[MohamedShawky]

Hey @jpadilla

i need to create nested serializers
can you help me?

[xxmatyuk]

Hi @jpadilla,

yesterday I was frustrated facing this issue, and today came up with the solution. It's hacky now, but I'll come up with the PR.

Normally, you should define such kind of structures in one place, so what I did is simply walked through all the links, collected nested objects and stored their properties with types and descriptoins in schema's root under 'definitions' . Later on, when encode._get_parameters is called, I simply check whether the field_type is object, and, if so, update schema_property with reference. Like this: {'$ref': '#/definitions/{}'.format(field.name)}

Works fine. There're also a few cases that should been handled, e.g. an array of objects, of even arrays should be handled the same way, but the idea of definitions seems to be good.

This is actual If you're using django-rest-swagger, since it uses openapi_codec (1.3.1 now) where the fix is expected to be (bug: core-api/python-openapi-codec#37)

[lucasmpaim]

+1

[kolanos]

@jpadilla Any updates on this issue?

[jpadilla]

@kolanos I'm not actively working on this at the moment.