django-rest-swagger似乎无法为我工作.我无法记录标题之外的任何内容

Question

似乎django-rest-swagger放弃了对YAML文档的支持,并用一种​​模糊的,没有记录的方式来替换它.我花了最后48小时试图了解如何记录我的post方法中的参数.

例如:我有这个:

class user_addresses(APIView):
    """
    get all addresses or post a new one
    """
    authentication_classes = ([JSONWebTokenAuthentication])

    def get(self, request, format=None):
        addresses = Address.objects.filter(owner_id=request.user.id)
        print (addresses)
        serializer = address_serializer(addresses, many=True)
        return Response(serializer.data)

    def post(self, request, format=None):
        serializer = address_serializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response({'success': True,
                            'result': serializer.validated_data},
                            status=status.HTTP_201_CREATED)
        return Response({'success': False,
                        'result': serializer.errors},
                        status=status.HTTP_400_BAD_REQUEST)

但是django-rest-swagger会将其显示为:

有人能指出我的方向,我可以定义swagger允许的所有丰富数据,如帖子字段名称,如果他们是强制性的.我只是疯了,在这里跑圈而且找不到任何东西,但抱怨没有办法做到这一点.

Answer 1

因此2.0更新的想法是使用CoreAPI,即"内部"休息框架模式生成,并从中生成swagger规范.

CoreAPI使用序列化程序和视图类来完成它的工作.从序列化程序,它知道哪些字段是必需的,这些字段是什么类型,如果你想添加你的个人描述,你可以使用help_text参数:

some_field = serializers.Field(help_text='Field description')

在您的情况下,问题是它将无法理解APIView序列化程序与您的序列化程序之间的关系.我建议采取额外的步骤,转移到通用视图或视图集,所有这些都支持serializer_class可用于内省的属性.对于你的例子,这样的东西应该工作:

# serializer
class AddressSerializer(serializers.ModelSerializer):

    line1 = serializers.CharField(help_text='Field documentation!')

    class Meta:
        model = Address
        fields = '__all__'
        read_only_fields = 'owner',

    def create(self, validated_data):
        validated_data['owner'] = self.context['request'].user
        return super().create(validated_data)


# api class-based view
class UserAddresses(generics.ListCreateAPIView):
    """
    General API documentation (not wisible in the swagger view)

    get:
    GET-specific documentation!

    Lorem ipsum

    post:
    POST-specific documentation!

    Dolor **sit amet**
    """
    authentication_classes = ([JSONWebTokenAuthentication])
    permission_classes = permissions.IsAuthenticated,
    serializer_class = AddressSerializer

    def get_queryset(self):
        return Address.objects.filter(owner_id=self.request.user.id)

对于视图,有一种特定的docstirng格式,它非常简单,希望能够提高加班时间.无论如何,你现在应该有更多可接受的结果:

Answer 2

一个CoreAPI文档可以帮助你做出一个自定义扬鞭视图.Swagger使用coreapi json输入来呈现视图 - Django Rest Swagger使用CoreAPI的Python绑定生成JSON(https://github.com/core-api/python-client).

该coreapi.Document对象包含什么？

对于每个API,您可以创建一个coreapi.Link()对象.每个Link对象包含:

• 一个URL
• HTTP方法
• 描述
• 字段

字段列表必须包含coreapi.Field()对象.一个Field对象有参数:

• 名称
• 必填(该字段是否必填)
• 位置(路径参数或查询参数)
• 描述

一个例子

如果我们使用CoreAPI,示例Swagger Schema看起来像这样:

import coreapi

def api_schema_generator():
    api_schema = coreapi.Document(
        title="My Swagger",
        content={
            "User Addresses": {

                "int_api_get": coreapi.Link(
                    url="/int_api/v1/addresses/",
                    action="get",
                    description="Get addresses of a user",
                    fields=[
                        coreapi.Field(
                            name="user_id",
                            required=True,
                            location="path",
                            description="Unique ID of the user whose addresses are to be found"
                        ),
                    ]
                ),
                "int_api_post": coreapi.Link(
                    url="/int_api/v1/addresses/",
                    action="post",
                    description="Add address for a user",
                    fields=[
                        coreapi.Field(
                            name="user_id",
                            required=True,
                            location="path",
                            description="Unique ID of the user"
                        ),
                        coreapi.Field(
                            name="address",
                            required=True,
                            location="path",
                            description="Address of the user"
                        ),
                    ]
                )
            }
        }
    )
    return api_schema

我们的观点将此coreapi.Document对象作为输入.我们使用SwaggerUIRenderer,OpenAPIRenderer并CoreJSONRenderer装饰了我们的观点.

views.py:

from rest_framework.decorators import api_view, renderer_classes
from rest_framework_swagger import renderers as swagger_renderer
from rest_framework import renderers

@api_view()
@renderer_classes([renderers.CoreJSONRenderer,
                   swagger_renderer.OpenAPIRenderer,
                   swagger_renderer.SwaggerUIRenderer,
                   ])
def schema_view(request):
    api_schema = api_schema_generator()
    return response.Response(api_schema)

我们现在需要的只是我们视图的URL映射.

urls.py:

from django.conf.urls import include, url

urlpatterns = [
    url(r'^$', views.schema_view),
]

编写自定义招摇可能看起来有点单调乏味,但您可以完全控制要在Swagger视图中显示的数据.