排除特定 HTTP 方法的 swagger 文档答案

【问题标题】：Exclude swagger docs for specific HTTP methods排除特定 HTTP 方法的 swagger 文档
【发布时间】：2019-03-19 16:13:18
【问题描述】：

我使用 drf-yasg 为我的 Django REST API 生成 swagger 文档。我有几个端点，items/ 带有 GET、POST 和 DELETE 方法；和 items/ 仅使用 DELETE 方法。但是，生成的 swagger 文档错误地还包括后一个端点的 GET 和 POST。

这是我在 urls.py 中的一个 sn-p：

urlpatters = [
    url(r'^items/$', views.ItemViewSet.as_view()),
    path('items/<uuid:itemID>', views.ItemViewSet.as_view()),
]

views.py 包含如下内容：

class ItemViewSet(mixins.DestroyModelMixin, GenericAPIView):
    def get(self, request):
            # ...
            return Response(HTTP_200_OK)

    def post(self, request):
            # ...
            return Response(status=status.HTTP_201_CREATED)

    def delete(self, request, itemID):
             # ...
             return Response(status=status.HTTP_204_NO_CONTENT)

    def delete(self, request):
            # ...
            return Response(status=status.HTTP_204_NO_CONTENT)

如何从 items/ 文档中排除 GET 和 POST？

我已经阅读了https://github.com/axnsan12/drf-yasg/blob/master/docs/custom_spec.rst 和 Exclude URLs from Django REST Swagger 但还没有找到可行的解决方案。

【问题讨论】：

我可以通过指定一个自定义的 SwaggerAutoSchema 类来微调 get_operation() 中的操作，从而创建一个 hacky 解决方法。除非出现更好的解决方案，否则我稍后会将此作为答案发布。
你的帖子有什么消息吗？
@Zulu 我发布了自己的解决方法。

标签： django swagger drf-yasg

【解决方案1】：

我的黑客解决方案：

class SwaggerAutoSchemaMethodExclusion(SwaggerAutoSchema):
    read_op_counter = 0
    create_op_counter = 0       

    def get_operation(self, operation_keys):
        if "create" in in operation_keys:
            SwaggerAutoSchemaMethodExclusion.create_op_counter += 1
            if SwaggerAutoSchemaMethodExclusion.create_op_counter % 2 == 0:
                return None
        elif "read" in operation_keys:
            SwaggerAutoSchemaMethodExclusion.read_op_counter += 1
            if SwaggerAutoSchemaMethodExclusion.read_op_counter % 2 == 0:
                return None

        return super().get_operation(operation_keys)


class ItemViewSet(mixins.DestroyModelMixin, GenericAPIView):
    swagger_schema = SwaggerAutoSchemaMethodExclusion
    // ...

【讨论】：

【解决方案2】：

您可以通过在您的views.py 中设置swagger_schema = None 从文档中排除API 端点

  class MyView(generics.ListCreateAPIView):
    """MyView class doc."""
    swagger_schema = None

    def get(self, response):
        # Do stuff here

来源：https://github.com/axnsan12/drf-yasg/commit/a211184478e6f0ca348312438c9c29d7b535b0fa

【讨论】：

此解决方案不排除 items/ 和 items/ 吗？我只想排除其中一个。

【解决方案3】：

如果你使用 ViewSet（不是 APIView），你可以使用 @action 装饰器 https://drf-yasg.readthedocs.io/en/stable/custom_spec.html

在我的项目中

class MyEntityViewSet(ModelViewSet):

@swagger_auto_schema(tags=['your tag here'])
@action(methods=['get'], detail=False)
def list(self, request):
    list obtaining code here

@swagger_auto_schema(tags=['your tag here'])
@action(methods=['post'], detail=True)
def create(self, request):
    creation code here

@swagger_auto_schema(tags=['your tag here'], method='delete')
@action(methods=['delete'], detail=True)
def destroy(self, request, entity_id, **kwargs):
    deletion code here 
#same with update

然后在 urls 文件中：

path('my-api/', MyEntityViewSet.as_view({'get': 'list', 'post': 'create'})),
path('my-api/<int:entity_id>/', MyEntityViewSet.as_view({'put': 'update', 'delete': 'destroy'})),

【讨论】：