django-rest-frameworkswaggerschemadocumentationopenapi

Openapi - duplicate operationID and extra parameter


I'm documenting my Django API using Swagger.When I generate my Openapi schema, a second route with an additional parameter {format} is added for each of my paths, with the same operation ID as the "correct" route.

I read that the generator may generate duplicate operationId if I have several views with the same model, but this is not my case I think.

Overall, my views (resource/api/views.py) are all organized like this:

class ResourceList(APIView):

    """
    View to list Resources.
    """

    def get(self, request, parameter1):
       ...

class ResourceDetail(APIView):

    """
    View to retrieve information of a Resource.
    """

    def get(self, request, parameter1, parameter2):
        ...

For these two views, I have these two paths:

urlpatterns = ([
    path('<str:parameter1>', views.ResourceList.as_view()),
    path('<str:parameter1>/details/<str:parameter2>', views.ResourceDetail.as_view())
])

And the schema generator generates two routes for each.

For the first path:

Route: /api/resource/{parameter1}, Method: get
Route: /api/resource/{parameter1}{format}, Method: get

For the second path:

Route: /api/resource/{parameter1}/details/{parameter2}, Method: get
Route: /api/resource/{parameter1}/details/{parameter2}{format}, Method: get

A warning like this appears:

Route: /api/resource/{parameter1}, Method: get
Route: /api/resource/{parameter1}{format}, Method: get
An operationId has to be unique across your schema. Your schema may not work in other tools.

The warning obviously makes sense, because both routes have the same operationID,(retrieveResourceList in this case). What I don't understand is why the second route is being generated and where that format parameter comes from.

Is this a normal behaviour? If not, what am I doing wrong?


Solution

  • This might not be the way to resolve this fully but in my case, I try commenting the format_suffix_patterns and the format parameter disappear. Here is how I manage the urls:

    from rest_framework.urlpatterns import format_suffix_patterns
    
    urlpatterns = [...]
    
    urlpatterns = format_suffix_patterns(urlpatterns) # Comment this