DRF YASG定制 [英] DRF YASG Customizing

问题描述

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

I'm trying to customize my api documentation buuild with yasg.

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

First off, I would like to determine the naming of my own sections, and what endpoints should be included in this section. It seems that the naming of sections is based on the first prefix not belonging to the longest common prefix e.g.:

如果我们拥有api/v1/message和api/v1/test网址，则这些部分将被命名为message和test.我有办法确定此部分的自定义命名吗?

if we have the urls api/v1/message and api/v1/test than the sections will be named message and test. Is there a way for me to determine A custom naming for this section?

此外，每个部分的介绍都是空的，如何在此处添加文本?

Furthermore, the introduction of every section is empty, how do I add text here?

最后但并非最不重要的一点，Stripe具有这些惊人的分区分隔符，我如何在drf yasg中添加这些分区分隔符.

And last but not least, Stripe has these amazing section dividers how can I add these in drf yasg.

推荐答案

当前，我正在使用API​​View和@swagger_auto_schema定义端点的文档.

Currently, I'm using APIView and @swagger_auto_schema to define the documentation of my endpoint.

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

In the code below, you can see how to add more information to define your endpoint. I hope it helps you

##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中测试以下行的注释

By last, if you want to see your endpoints in groups by link, you can test commenting the line below in yours urls.py

#urlpatterns = format_suffix_patterns(urlpatterns)

下面是您应如何查看的屏幕

Below, some screen of how you should see it

[home][1]
[Get all categories][2]
[Post a new category][3]
[Endpoints in groups][4]

You can find more information in the link below

https://drf-yasg.readthedocs.io/en/stable/custom_spec.html

  [1]: https://i.stack.imgur.com/iwsnB.png
  [2]: https://i.stack.imgur.com/R7f1q.png
  [3]: https://i.stack.imgur.com/1ia9F.png
  [4]: https://i.stack.imgur.com/Gwckf.png

这篇关于DRF YASG定制的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！