如何记录基于函数的视图参数? [英] How to document function-based views parameters?

问题描述

我正在使用Django 1.11和Django REST Framework 3.7开发REST API.我安装了 Django REST Swagger 2.1来生成文档.

I'm developing a REST API with Django 1.11 and Django REST Framework 3.7. I installed Django REST Swagger 2.1 to generate the documentation.

我正在使用基于函数的视图，如下所示:

I'm using a function-based view like this:

from rest_framework.decorators import api_view, permission_classes

@api_view(['POST'])
@permission_classes((permissions.AllowAny,))
def jwt_auth(request, provider, format=None):
    """
    View description here
    """
    pass

如您所见，Swagger可以识别我的视图，并具有正确的描述:"在此处查看描述".

As you can see, my view is recognized by Swagger and it has the correct description: "View description here".

但是:

• 您可以看到provider URL参数的"描述"列为空.
• 未记录POST参数(显然，因为Swagger无法知道它们)

• You can see the "Description" column is empty for the provider URL parameter.
• The POST parameters are not documented (obviously, because there is no way for Swagger to know them)

如何编写基于函数的视图的URL和POST参数以及响应的文档?

我尝试了 YAML文档字符串，但是似乎是针对旧版本(0.3.x)的版本，不适用于版本2.x.

I tried YAML Docstrings but it seems it's for the old version (0.3.x) and it doesn't work with version 2.x.

推荐答案

您可以使用DjangoRestFrameWork架构. http://www.django-rest-framework.org/api-guide/schemas/

You can use Schema of DjangoRestFrameWork. http://www.django-rest-framework.org/api-guide/schemas/

您可以尝试以下方法.

from rest_framework.decorators import api_view, permission_classes, schema
@api_view(['POST'])
@permission_classes((permissions.AllowAny,))
@schema(custom_schema)
def jwt_auth(request, provider, format=None):
    """
    View description here
    """
    pass

---

自定义架构定义

---

custom schema defintion

import coreapi, coreschema
from rest_framework.schemas import AutoSchema, ManualSchema
custom_schema = AutoSchema(manual_fields=[
    coreapi.Field("username", required=True, location="form", type="string", description="username here"),
    coreapi.Field("password", required=True, location="form", type="string", description="password field"
]

应该做到这一点. 有关更多详细信息，请访问我在顶部提供的链接.基本的POST和GET参数应以这种方式工作.

Should do the trick. For more detailed info, visit the link I provided at the top. Basic POST and GET parameters should work in this way.

这篇关于如何记录基于函数的视图参数?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！