Openapi - 重复的 operationID 和额外的参数

Question

我正在使用 Swagger 记录我的 Django API。当我生成我的 Openapi 架构时，为我的每个路径添加了带有附加参数

{format}

的第二条路线，具有与“正确”路线相同的操作 ID。

我读到如果我有几个相同模型的视图，生成器可能会生成重复的 operationId，但我认为这不是我的情况。

总的来说，我的视图（resource/api/views.py）都是这样组织的：

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):
        ...

对于这两个view，我有这两条路径：

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

模式生成器为每个生成两条路线。

对于第一条路径：

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

对于第二条路径：

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

出现这样的警告：

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.

警告显然是有道理的，因为两条路线具有相同的操作ID，（

retrieveResourceList

在这种情况下）。我不明白的是为什么要生成第二条路线以及

format

参数来自哪里。

这是正常行为吗？如果不是，我做错了什么？

Answer 1

我正在使用 Autoschema 来覆盖 operation_id

from rest_framework.schemas.openapi import AutoSchema
class CandidateAssignToMeList(CandidateMixins,generics.ListAPIView):
    schema = AutoSchema(
        tags=['LISTVIEW'],
        component_name='Assign To Me',
        operation_id_base='CandidateAssignToMeList',
    )
class CandidateList(CandidateMixins,generics.ListAPIView):
     schema = AutoSchema(
        tags=['LISTVIEW'],
        component_name='Candidate ListView',
        operation_id_base='CandidateList',
    )

Answer 2

这可能不是完全解决这个问题的方法，但就我而言，我尝试评论

format_suffix_patterns

和

format

参数消失。这是我管理网址的方式：

from rest_framework.urlpatterns import format_suffix_patterns

urlpatterns = [...]

urlpatterns = format_suffix_patterns(urlpatterns) # Comment this

Answer 3

我不确定这是否适用于您的特定情况 - 似乎 AutoSchema 无论如何都可能获得唯一的 OperationID，但是......

您可以始终手动指定用于生成所有操作标识符的 operation_id_base。这可以防止出现重叠的 operationIds 和相应错误的问题：

from rest_framework.schemas.openapi import AutoSchema    
class ResourceDetail(APIView):

    """
    View to retrieve information of a Resource.
    """
    schema = AutoSchema(operaton_id_base='resource_detail')
    def get(self, request, parameter1, parameter2):
        ...