django-rest-framework选项中的文档API

Question

我正在编写我的第一个REST API (使用django-rest-framework)。

我正在添加URL参数来过滤结果。我的理解是，这些参数的文档属于选项动词。我的代码：

class SuburbViewSet(viewsets.ReadOnlyModelViewSet):
    """
    Retrieves the suburbs (20 per page).
    GET and OPTIONS allowed.
    """
    model = Suburb
    serializer_class = SuburbSerializer

    def get_queryset(self):
        """
        Can filter by region_id, ...
        - using query parameters in the URL.
        """
        queryset = Suburb.objects.all()
        region_id = self.request.QUERY_PARAMS.get('region_id', None)
        if region_id is not None:
            queryset = queryset.filter(region_id=region_id)
        return queryset

    def metadata(self, request):
        ret = super(SuburbViewSet, self).metadata(request)

        ret['parameters'] = {
            "page": {
                "type": "integer",
                "description": "The page number",
                "required": False
            },
            "region_id": {
                "type": "integer",
                "description": "The region ID to filter the results",
                "required": False
            }
        }

        return ret

这是最好的/唯一的REST方式吗(解释选项中的参数)？

关于django-rest-framework，我已经扩展了元数据(self，request)，这让我觉得很麻烦。我是不是错过了一些设置参数描述的内置方法？

谢谢！

Answer 1

作为对OPTIONS请求的响应，通用视图已经包含了参数描述。

例如，完成本教程后，您应该能够发出OPTIONS请求并检查可用的操作。

请确保将--user选项设置为一个现有的用户/密码，否则您将只有ready-only访问权限，无法获得响应的actions部分。

bash: curl -X OPTIONS --user amy:amy -v http://127.0.0.1:8000/snippets/ -H 'Accept: application/json; indent=4'; echo
* About to connect() to 127.0.0.1 port 8000 (#0)
*   Trying 127.0.0.1... connected
* Server auth using Basic with user 'amy'
> OPTIONS /snippets/ HTTP/1.1
> Authorization: Basic YW15OmFteQ==
> User-Agent: curl/7.22.0 (x86_64-apple-darwin11.2.0) libcurl/7.22.0 OpenSSL/1.0.0e zlib/1.2.5 libidn/1.22
> Host: 127.0.0.1:8000
> Accept: application/json; indent=4
> 
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Date: Fri, 28 Jun 2013 09:27:01 GMT
< Server: WSGIServer/0.1 Python/2.7.2
< Vary: Accept, Cookie
< Content-Type: application/json; indent=4; charset=utf-8
< Allow: GET, POST, HEAD, OPTIONS
< 
{
    "name": "Snippet List", 
    "description": "This endpoint presents code snippets.\n\nThe `highlight` field presents a hyperlink to the hightlighted HTML\nrepresentation of the code snippet.\n\nThe **owner** of the code snippet may update or delete instances\nof the code snippet.\n\nTry it yourself by logging in as one of these four users: **amy**, **max**,\n**jose** or **aziz**.  The passwords are the same as the usernames.", 
    "renders": [
        "application/json", 
        "text/html"
    ], 
    "parses": [
        "application/json", 
        "application/x-www-form-urlencoded", 
        "multipart/form-data"
    ], 
    "actions": {
        "POST": {
            "url": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }, 
            "highlight": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }, 
            "owner": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }, 
            "title": {
                "type": "string", 
                "required": false, 
                "read_only": false, 
                "label": "title", 
                "max_length": 100
            }, 
            "code": {
                "type": "string", 
                "required": true, 
                "read_only": false, 
                "label": "code"
            }, 
            "linenos": {
                "type": "boolean", 
                "required": false, 
                "read_only": false, 
                "label": "linenos"
            }, 
            "language": {
                "type": "multiple choice", 
                "required": true, 
                "read_only": false, 
                "label": "language"
            }, 
            "style": {
                "type": "multiple choice", 
                "required": true, 
                "read_only": false, 
                "label": "style"
            }
        }
    }
}

您也可以通过browsable API发出OPTIONS请求。