django - DRF YASG 定制

Question

我正在尝试使用 yasg 自定义我的 api 文档。

首先，我想确定我自己的部分的命名，以及本部分应包含哪些端点。似乎部分的命名是基于不属于最长公共前缀的第一个前缀，例如：

如果我们有 api/v1/message 和 api/v1/test 的 URL，那么这些部分将被命名为 message 和 test。有没有办法让我确定此部分的自定义命名？

再者，每一节的介绍都是空的，怎么在这里加文字呢？

最后但并非最不重要的一点是，Stripe 有这些令人惊叹的部分分隔符，我如何在 drf yasg 中添加这些。

Answer 1

目前，我正在使用 APIView 和 @swagger_auto_schema 来定义我的端点的文档。

在下面的代码中，您可以看到如何添加更多信息来定义您的端点。希望对你有帮助

##serializers.py

class CategorySerializer(serializers.ModelSerializer):
    """
    Serializing Categories 
    """
    class Meta:
        model = Category
        fields = [
            'id', 'name', 'slug'
        ]
        read_only_fields = [
           'slug', 
        ]


##views.py

username_param = openapi.Parameter('username', in_=openapi.IN_QUERY, description='Username',
                                type=openapi.TYPE_STRING)
email = openapi.Parameter('email', in_=openapi.IN_QUERY, description='Email',
                                type=openapi.TYPE_STRING)  
category_response = openapi.Response('response description', CategorySerializer)    

class CategoryList(APIView):
    permission_classes = [AllowAny]
          
    @swagger_auto_schema(
        manual_parameters=[username_param, email],
        query_serializer=CategorySerializer,
        responses = {
            '200' : category_response,
            '400': 'Bad Request'
        },        
        security=[],
        operation_id='List of categories',
        operation_description='This endpoint does some magic',
    )
    def get(self, request, format=None):
        """
        GET:
        Return a list of all the existing categories.
        """
        categories = Category.objects.all()
        serializer = CategorySerializer(categories, many=True)
        return Response(serializer.data)


    @swagger_auto_schema(
        request_body=CategorySerializer,
        query_serializer=CategorySerializer,
        responses={
            '200': 'Ok Request',
            '400': "Bad Request"
        },
        security=[],
        operation_id='Create category',
        operation_description='Create of categories',
    )
    def post(self, request, format=None):
        """
        POST:
        Create a new category instance.
        """
        serializer = CategorySerializer(data=request.data)
        if serializer.is_valid():
            serializer.save(created_by=self.request.user)
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

最后，如果您想通过链接查看分组中的端点，您可以测试在您的 urls.py 中评论以下行

#urlpatterns = format_suffix_patterns(urlpatterns)

下面是一些你应该如何看待它的屏幕

您可以在以下链接中找到更多信息：https ://drf-yasg.readthedocs.io/en/stable/custom_spec.html