Django-rest-framework: All endpoints in automatic API documentation disappear when `api-token-auth` endpoint added

Created on 2 May 2017 · 5Comments · Source: encode/django-rest-framework

Steps to reproduce

Create ModelViewSets and Serializers. Register the ViewSets in a router:

class ResultSerializer(serializers.ModelSerializer):
    test = serializers.PrimaryKeyRelatedField(queryset=Test.objects.all())
    certification = serializers.PrimaryKeyRelatedField(queryset=Certification.objects.all())
    value = serializers.CharField()

    class Meta:
        model = Result
        fields = '__all__'

class ResultViewSet(ModelViewSet):
    queryset = Result.objects.all()
    serializer_class = ResultSerializer


router = DefaultRouter()
router.register(r'results', ResultViewSet)
urls = router.urls

Add router URLs and documentation URLs to URLconf:

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^certifications/', include('certifications.urls')),
    url(r'^docs/', include_docs_urls(title='API Documentation')),
]

Everything working as expected. Now add a token-based login endpoint URL as described here:

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^certifications/', include('certifications.urls')),
    url(r'^docs/', include_docs_urls(title='API Documentation')),
    url(r'^api-token-auth/', views.obtain_auth_token),
]

Expected behavior

The documentation for api-token-auth should appear alongside the rest of the API documentation.

Actual behavior

All documentation disappears, and is replaced with an entry for api-token-auth. There is also a header by the name of one of my applications, but nothing is under this header.

screen shot 2017-05-02 at 3 06 33 pm

Source

elmehalawi

Most helpful comment

I was also experiencing this issue, but was not aware of the cause, so thank you for pointing it out! I am using djangorestframework-jwt for my token views. I am also able to replicate it by having multiple APIs configured. For example, in my root Django URL config, I have:

urlpatterns = [
    ...
    url(r'^api/', include('api.urls')),
    url(r'^apiv2/', include('apiv2.urls')),
    url(r'^api(v\d+)?/auth/', include('rest_framework.urls', namespace='rest_framework')),
    # url(r'^api(v\d+)?/get-token/', obtain_jwt_token),
    # url(r'^api(v\d+)?/auth/refresh-token/', refresh_jwt_token),
    # url(r'^api(v\d+)?/auth/verify-token/', verify_jwt_token),
    ...
]

Neither api.urls or apiv2.urls has token or auth endpoints in it. The documentation is configured for /apiv2/docs/. The resulting documentation page ends up with two empty dropdowns named 'api' and 'apiv2'.

With the release of 3.6.3 today it is possible to work around it by limiting the patterns allowed for documentation. I created a /docs/ endpoint under each API version's root URL and limited it to API endpoints only in the same version API. I don't get an single doc page for all APIs but I am fine with that. #4979 has the details.

PeteAndersen on 12 May 2017

👍5

All 5 comments

Okay, so all the "certifications" documentation appeared again when I got rid of include for some reason.

import certifications.urls as certification_urls

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^docs/', include_docs_urls(title='API Documentation')),
    url(r'^api-token-auth/', views.obtain_auth_token),
] + certification_urls.urlpatterns

You'd then have to edit your URLs to get them to look the way you want, since this changes the URLs (since include let you add a prefix).

I'm not sure why that was a problem, but there you go.

elmehalawi on 3 May 2017

urlpatterns = [
    ...
    url(r'^api/', include('api.urls')),
    url(r'^apiv2/', include('apiv2.urls')),
    url(r'^api(v\d+)?/auth/', include('rest_framework.urls', namespace='rest_framework')),
    # url(r'^api(v\d+)?/get-token/', obtain_jwt_token),
    # url(r'^api(v\d+)?/auth/refresh-token/', refresh_jwt_token),
    # url(r'^api(v\d+)?/auth/verify-token/', verify_jwt_token),
    ...
]

PeteAndersen on 12 May 2017

👍5

Just included docs url in an ongoing project and it wasn't showing any of my methods. Wasn't able to figure out what causes it but limiting patterns fixed it. For anyone facing the same issue, the workaround is:

# Before:
urlpatterns = [
    url(r'^$', SomeRootView.as_view()),
    url(r'^cats/', include('cats.urls')),
    # ...
    url(r'^docs/', include_docs_urls(title='title')),
]

# After:
urlpatterns = [
    url(r'^$', SomeRootView.as_view()),
    url(r'^cats/', include('cats.urls')),
    # ...
]

urlpatterns.append(
    url(r'^docs/', include_docs_urls(title='title', patterns=urlpatterns))
)