Django-rest-framework: Documentation does not support subdocuments

[AndreasBackx]

Checklist

• [x] I have verified that that issue exists against the master branch of Django REST framework.
• [x] I have searched for similar issues in both open and closed tickets and cannot find a duplicate.
• [x] This is not a usage question. (Those should be directed to the discussion group instead.)
• [x] This cannot be dealt with as a third party library. (We prefer new functionality to be in the form of third party libraries where possible.)
• [x] I have reduced the issue to the simplest possible case.
• [ ] I have included a failing test as a pull request. (If you are unable to do so we can still accept the issue.)

Steps to reproduce

Use the new documentation feature with an API design like so:

/foo
    /bar
        /{pk}
/bar
    /foo
        /{pk}

Expected behavior

For the documentation to show all endpoints.

Actual behavior

The documentation only shows the titles for the root foo and bar urls.

You can see a more desired behaviour when you add the following code to the template document.html:

{% for section_key, section in document.data|items %}

...

    {% for document_key, document in section.data|items %}
        {% include "rest_framework/docs/document.html" %}
    {% endfor %}

...

{% endfor %}

I haven't looked into this too much, it's getting close to 2AM at the time of writing this. But the sidebar.html also needs to be changed. Currently an immediate fix isn't possible because the menu items are not in a separate template file. They need to be made recursive and put in their own template tag.

[RedBlueThing]

Thanks for writing this up Andreas. I had the same problem today and was happy to find someone had already raised the issue.

[carltongibson]

I have this as well:

    url(r'^main/$', MainView.as_view(), name='main'),
    url(r'^main/detail/$', DetailView.as_view(), name='detail'),

The schema is correct:

> // in the JS console
> schema.content.main.hasOwnProperty('detail')
true

But DetailView is not displayed in the docs.

Not there yet but, I assume the above analysis is correct. What kind of tests do we need here?

[carltongibson]

I was able to get _OK_ first results adding similar to @AndreasBackx's suggestion to document.html:

    {% for nested_key, nested_document in section.data|items %}
        {% include "rest_framework/docs/nested_document.html" %}
    {% endfor %}

Where nested_document.html just reproduces the actual link inclusion:

{% load rest_framework %}

<h3 id="{{ section_key}}-{{ nested_key }}">
{{ section_key}}-{{ nested_key }} <a href="#{{ section_key}}-{{ nested_key }}"><i class="fa fa-link" aria-hidden="true"></i></a>
</h3>

{% if nested_document.description %}
<p>{% render_markdown nested_document.description %}</p>
{% endif %}


{% for link_key, link in nested_document.links|items %}
  {% with section_key|add:'-'|add:nested_key as section_key %}
      {% include "rest_framework/docs/link.html" %}
  {% endwith %}
{% endfor %}

In sidebar.html, I just added a loop:

{% for nested_key, nested_document in section.data|items %}
    <li><a href="#{{ section_key}}-{{ nested_key }}">{{ section_key}}-{{ nested_key }}</a>
      <ul style="margin-left:10px;">
      {% for link_key, link in nested_document.links|items %}
          <li><a href="#{{ section_key}}-{{ nested_key }}-{{ link_key }}">{{ link.title|default:link_key }}</a></li>
      {% endfor %}
      </ul>
    </li>
{% endfor %}

As I say, this was OK. (It's not recursive. The sidebar styling isn't perfect. But...)

I guess my next question is _What counts as "In-Scope" here?_

[carltongibson]

One more observation here:

{% with section_key|add:'-'|add:nested_key as section_key %}

The with block is required to allow anchors to function, but it breaks the JavaScript data binding in the Interact form:

<form data-key='["{{ section_key }}", "{{ link_key }}"]' class="api-interaction">

The correct value (which works) is something like:

'["{{ section_key }}","{{ nested_key }}","{{ link_key }}"]'

So, ideally, at each stage where a _key-path_ is manipulated it should just get the list, with tags etc to do the actual work.

[parisk]

I created this sample project which recreates this issue. It's a "snippet hosting" app, where you can view snippets in the following format:

http://apihost.com/users/{user_id}/snippets

You can take a look a it at https://github.com/parisk/snippethost.

Don't mean to nag here, but I'd like to ask if there are any plans for this or any suggested workaround.

[carltongibson]

@parisk I think at this stage you're going to need to look at adjusting the document/sidebar/link templates in line with suggestions in this thread. (Currently those are the workarounds.)

[parisk]

Should I do this in my own fork, or can I use my own templates somehow and instruct the API documentation use these, instead of the "stock" ones?

[carltongibson]

@parisk Assuming your TEMPLATE settings are in place, if you create a rest_framework/docs template folder you can override the supplied templates. (I didn't click the links but this "django override templates" Google search looks like it would give you all the info you need if you're unsure.)

The Interactive API Docs are all new, so you have to expect flexibility will improve over time. Adding custom templates is (almost certainly) always going to be a factor.

Lots of people are working on this: follow the issue tracker; see #5169 #5166 #5064 and others...

[parisk]

Thanks a lot @carltongibson. Tried this out and worked great 👍 .

I would be more than happy to contribute my templates back, but since there is already a PR open, I'd prefer not to flood the project.

[carltongibson]

@parisk If you have comments with specific lessons you've learnt, I'm sure those would be useful.

If you can't (sensibly) add those as comments on an open issue/PR then a new PR referencing the old-one with a good description of your point helps. (We can always close it again 🙂)

At this point we're still learning what people need so (to a point) more input is better (IMO) (especially if it's considered input)

[ConorMcGee]

Anyone know what the status of this is? Enthusiastic about the built-in docs but this makes them unusable in our case. Is help needed?

As an aside, is this not an unusually huge bug for DRF? Any time I've encountered something this bad it's always meant it was actually me who'd created a bad design pattern. Is that the case here?

[carltongibson]

@mcgeeco Help is always needed 😄 — Yes. Input welcome.

The issue here is coming up with changes to the bundled templates that will be generic enough for all purposes. (Or the 80% at least) Or else documenting the limitations and guiding users on how and where to override the templates.

... is this not an unusually huge bug for DRF?

It's a question of maturity I think. Most of DRF is several years old. It's had a long time for the issues to be worked out. Schema generation, and automatic doc generation based on that, is new — this is the first version — so we're all learning the limitations (and looking for the solutions) together.

...unusable...

It shouldn't be beyond a user to override the templates. That's almost certainly going to be part of the final solution even as it matures.

[ddahan]

I just noticed @tomchristie added the issue to the 3.6.4 release milestone, which is a good news, as I guess this bug is critical for many of us.
Sorry for posting this question here, it's probably not the place, but is there a way to know when the 3.6.4 is supposed to be released? I can see on the page: Past due by about 1 month - 39% complete.

I'm considering switching back to swagger because I can't use the embedded doc right now, but there's no point doing this if I just need to wait for a few days more.

Thanks!

[parisk]

@ddahan I got the newsletter from Encode and looks like the release will be out next week 😄.

[carltongibson]

I know there's a lot of interest in this issue. #5335 looks like a good candidate fix. If you could install that and give it a run, feedback on the PR (i.e. on #5335) would be very useful.

[carltongibson]

Closed by #5334