Django，drf-yasg - 如何为标签添加描述？

Question

Swagger 文档说你可以这样做：

https://swagger.io/docs/specification/grouping-operations-with-tags/

但不幸的是 drf-yasg 没有实现这个功能：

https://github.com/axnsan12/drf-yasg/issues/454

据说，我可以添加自定义生成器类，但这是一个非常笼统的答案。现在我看到了drf_yasg.openapi.Swaggerget infoblock 并且我有想法，这可能是将全局tags部分作为附加 init 参数的正确位置，但它比自定义生成器类更深入，而且我对此模块缺乏了解

有没有人有解决这个特定问题的方法，或者至少可能是某种教程的链接，如何正确自定义生成器类？

Answer 1

不确定这是否正是您正在寻找的，但我认为这可能会有所帮助。

要设置标签，我使用，可以通过几种不同的方式应用标签，主要取决于项目中使用的@swagger_auto_schema decorator类型。完整的详细信息可以在此处的Views文档中找到。

当使用Views衍生自时APIView，你可以这样做：

class ClientView(APIView):
    @swagger_auto_schema(tags=['my custom tag'])
    def get(self, request, client_id=None):
        pass

根据文档，限制是tags仅将 strs 列表作为值。因此，从现在开始，我相信不支持标签上的额外属性，如 Swagger 文档中所述，此处。

无论如何，如果您只需要定义摘要或描述来获取如下图所示的内容，则可以使用装饰器或类级文档字符串来定义它们。这是一个例子：

class ClientView(APIView):
    '''
    get:
    Client List serialized as JSON.

    This is a description from a class level docstring.

    '''
    def get(self, request, client_id=None):
        pass
    
    @swagger_auto_schema(
        operation_description="POST description override using 
            decorator",
        operation_summary="this is the summary from decorator",
        
        # request_body is used to specify parameters
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            required=['name'],
            properties={
                'name': openapi.Schema(type=openapi.TYPE_STRING),
            },
        ),
        tags=['my custom tag']
    )
    def post(self, request):
        pass

祝你好运！

Answer 2

不幸的是，这是drf-yasg当前的一个问题。

要真正实现这一点，您需要创建自己的模式生成器类：

from drf_yasg.generators import OpenAPISchemaGenerator

class CustomOpenAPISchemaGenerator(OpenAPISchemaGenerator):
  def get_schema(self, request=None, public=False):
    """Generate a :class:`.Swagger` object with custom tags"""

    swagger = super().get_schema(request, public)
    swagger.tags = [
        {
            "name": "api",
            "description": "everything about your API"
        },
        {
            "name": "users",
            "description": "everything about your users"
        },
    ]

    return swagger

确保将其也包含在您的架构视图中

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
  openapi.Info(
    title="My API",
    default_version='v1',
  ),
  generator_class=CustomOpenAPISchemaGenerator,
)

希望这对你有用！