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.Swagger获得了info块，我认为这可能是将全局tags部分作为附加初始化参数的正确位置，但它比定制生成器类更深入，而且我对此模块缺乏了解

有没有人有解决这个特殊问题的方法，或者至少有一个指向某种教程的链接，如何正确地定制生成器类？

Answer 1

我不确定这是否是你想要的，但我认为它可能会有所帮助。

为了设置标签，我使用了@swagger_auto_schema decorator，它可以以几种不同的方式应用，主要取决于项目中使用的Views类型。完整的详细信息可以在docs here上找到。

当使用从APIView派生的Views时，您可以这样做：

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

根据docs，限制是tags仅接受strs列表作为值。因此，从现在开始，我相信不会像Swagger docs，here中所说的那样，在标签上支持额外的属性。

无论如何，如果您只需要定义一个摘要或描述来获得类似下面的图像，那么您可以使用装饰器或类级文档字符串来定义它们。下面是一个示例：

​

​

​

​

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的current issue。

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

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,
)

希望这对你有用！