Django-rest-framework: URLPathVersioning results in empty Built-in API documentation

[grantmcconnaughey]

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

Django 1.10.6. Using the following code:

# Configuration
REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
}

# URLS
router = routers.DefaultRouter()
router.register(r'items', views.ItemViewSet)

urlpatterns = [
    url(r'^api/(?P<version>v1)/', include(router.urls, namespace='api')),
    url(r'^docs/', include_docs_urls(title='API')),
]

# View set
class ItemViewSet(viewsets.ModelViewSet):

    queryset = Item.objects.all()
    serializer_class = ItemSerializer

# Serializer
class ItemSerializer(serializers.ModelSerializer):
    actions = ActionSerializer(many=True)
    inputs = InputSerializer(many=True)

    class Meta:
        model = Item
        fields = ('queue', 'title', 'content', 'queue_date', 'source',
                  'assignee', 'actions', 'inputs')

Expected behavior

The API should be rendered.

Actual behavior

API documentation page is empty. Removing the version portion of the API URL pattern (url(r'^api/', include(router.urls, namespace='api'))) does fix the issue, but then I don't have a versioned API anymore.

[eamigo86]

Same issue

[EricPobot]

I have the same issue, even when removing any versionning (I was not using DEFAULT_VERSIONING_CLASS setting anyway).

My API is decomposed into several Django apps and thus the url routing declaration uses includes. But it does not seem to change anything if I "push" everybody to the top level.

[kgodey]

Is there a workaround for this issue? This bug is making it impossible for our project to use the built-in API documentation since we have multiple versions of our API in production and can't change the URLs.

[tomchristie]

Is there a workaround for this issue?

Not that I know of, no.

It's important enough that I'd like to see it highly prioritized, but there's a lot of other things going on at the moment too. Even after we release 3.6.3, there's still also all the work towards 3.7.0's realtime integration.

I'm going to milestone this for 3.7, since it's probably moderately involved to resolve this, and we'll need to be able to support hosting multiple versions of the API docs. Perhaps we'll be able to resolve it sooner, or perhaps someone will come up with a good way of resolving this (a partially bound reverse function that already includes the version, perhaps?)

[kgodey]

@tomchristie Thanks for the update! I think I found a workaround for 3.6.3 based on the latest master branch, which adds a patterns parameter to the include_docs_urls function. I used it to pass in the URL patterns of only our latest API version, and that allowed the auto generated documentation to work. I've only tested it with one version, but I think it might work for multiple versions as long as you were willing to have different URLs for each version.

e.g. in urls.py

api_v1_urls = [
    # url patterns here
]

api_v2_urls = [
    # url patterns here
]

urlpatterns += api_v1_urls
urlpatterns += api_v2_urls

url(r'^api_v1_documentation/', include_docs_urls(title='API v1 docs', patterns=api_v1_urls))
url(r'^api_v2_documentation/', include_docs_urls(title='API v2 docs', patterns=api_v2_urls))

This doesn't work in 3.6.2, though, because patterns hasn't been added as an argument to the function yet.

[tomchristie]

Okay great. 3.6.3 will be just around the corner (this week or next)

[carltongibson]

This was fixed as a consequence of #5334, released as part of 3.6.4.

[zhexiao]

@carltongibson

Dear, carltongibson,

Can you teach me or tell me how can i display the ApiView parameters on the Docs? I cannot find any documents about that.

Thanks a lot.