Django 之REST framework学习7:Schemas & client libraries

最新推荐文章于 2024-05-09 06:00:00 发布

Quincy379

最新推荐文章于 2024-05-09 06:00:00 发布

阅读量992

点赞数

Django REST framework 专栏收录该内容

12 篇文章 1 订阅

订阅专栏

声明：

如果你不小心刚好看到此文，然后又刚好感到恶心呕吐头昏眼花，说明两点：一你刚好怀上了，二你刚好病了，为解决不适，请离开这里抓紧就医！！！
如有不明白的地方，请移步：
http://www.django-rest-framework.org/tutorial/7-schemas-and-client-libraries/

Schemas是指机器可读的文件，这个文件包含可用API 的endpoints，他们的URLs，和他们支持的操作.。
Schemas是一个非常有用的工具，他可以用来自动生成文档，也可以用于动态的驱动client libraries与API进行交互。

Core API：

为了提供schema 支持，REST framework使用了Core API。

Core API是一个用于描述API的文档说明书，它被用于提供可用endpoints的内部表现形式和API暴露出可能的交互，它既可以用于客户端，又可以用于服务端。

当在服务端使用时，Core API允许API 支持渲染成宽泛的schema，或者超媒体格式。（其实我也不懂什么意思，老外这用词真的是，希望国人团结努力，创造自己的编程语言，然后老外来翻译我们的文档，恶心死他们~）
当在客户端使用时，Core API可以用于动态驱动 client libraries与任意的API（这些API有能被支持的schema或者超媒体格式）进行交互。

添加schema

REST framework既支持被明确定义的schema视图，又能自动生成schemas。当我们使用viewsets 和 routers，我们可以使用自动的 schema 生成工具。
想要使用 API schema，必须安装coreapipython包：

$ pip install coreapi

在我们URL路由中加入一个自动生成的schema 视图，这时我们就有了API的schema。

from rest_framework.schemas import get_schema_view

schema_view = get_schema_view(title='Pastebin API')

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

如果你在浏览器中访问API的根endpoint，现在你应该可以看见corejson作为一个选项已经可用了。

corejson-format

在Accept请求头中指明需要的内容类型后，我们可以从命令行中请求一个schema ：

$ http http://127.0.0.1:8000/schema/ Accept:application/coreapi+json
HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/coreapi+json

{
    "_meta": {
        "title": "Pastebin API"
    },
    "_type": "document",
    ...

默认输出形式是用的Core JSON编码。
别的schema 格式，比如Open API也是支持的。

使用命令行的客户端：

既然API暴露出schema endpoint，那么我们可以使用动态的客户端库去和API交互，要演示这个就要使用Core API 的命令行客户端。
coreapi-cli包可以提供命令行客户端的功能：

$ pip install coreapi-cli

现在试一下：

$ coreapi
Usage: coreapi [OPTIONS] COMMAND [ARGS]...

  Command line client for interacting with CoreAPI services.

  Visit http://www.coreapi.org for more information.

Options:
  --version  Display the package version number.
  --help     Show this message and exit.

Commands:
...

首先我们使用命令行客户端加载API的schema

$ coreapi get http://127.0.0.1:8000/schema/
<Pastebin API "http://127.0.0.1:8000/schema/">
    snippets: {
        highlight(id)
        list()
        read(id)
    }
    users: {
        list()
        read(id)
    }

我们还没有授权，现在只能看到只读的endpoints，和我们在API上设置的权限一致！
让我们用命令行客户端罗列下现有的snippets：

$ coreapi action snippets list
[
    {
        "url": "http://127.0.0.1:8000/snippets/1/",
        "id": 1,
        "highlight": "http://127.0.0.1:8000/snippets/1/highlight/",
        "owner": "lucy",
        "title": "Example",
        "code": "print('hello, world!')",
        "linenos": true,
        "language": "python",
        "style": "friendly"
    },
    ...

一些API的endpoints需要命名参数，例如，为了给特定的snippet获取高亮的HTML，我们需要提供一个id。

$ coreapi action snippets highlight --param id=1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
<head>
  <title>Example</title>
  ...

客户端认证：

如果我们需要增删改snippets，我们就需要授权，这次我们只使用基本的认证。
下面的<username>和<password>记得用你真实的名字和密码去替换：

$ coreapi credentials add 127.0.0.1 <username>:<password> --auth basic
Added credentials
127.0.0.1 "Basic <...>"

现在我们如果再次获取schema，我们就能看到完整的可用的交互了：

$ coreapi reload
Pastebin API "http://127.0.0.1:8000/schema/">
    snippets: {
        create(code, [title], [linenos], [language], [style])
        delete(id)
        highlight(id)
        list()
        partial_update(id, [title], [code], [linenos], [language], [style])
        read(id)
        update(id, code, [title], [linenos], [language], [style])
    }
    users: {
        list()
        read(id)
    }

现在我们可以和这些endpoints交互了，例如创建一个新的snippet：

$ coreapi action snippets create --param title="Example" --param code="print('hello, world')"
{
    "url": "http://127.0.0.1:8000/snippets/7/",
    "id": 7,
    "highlight": "http://127.0.0.1:8000/snippets/7/highlight/",
    "owner": "lucy",
    "title": "Example",
    "code": "print('hello, world')",
    "linenos": false,
    "language": "python",
    "style": "friendly"
}

要删除snippet：

$ coreapi action snippets delete --param id=7

开发者既可以使用命令行客户端与API交互，也可以使用client libraries。Python 端的现在已经可以用了，JS版的马上就会发布。
要获取更多关于自定制schema generation和使用Core API client libraries的信息请参考完整的文档。

回顾（老外这回顾就不翻译了，没有什么实质性的东西！）

bla,bla,bla~

后续我会根据开发中对REST framework理解在翻译过程中使用不恰当的词进行纠正，也请提出宝贵意见，让我们共同完善，共同提高，共同进步！

Quincy379

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Django 之REST framework学习7:Schemas & client libraries

声明：如果你不小心刚好看到此文，然后又刚好感到恶心呕吐头昏眼花，说明两点：一你刚好怀上了，二你刚好病了，为解决不适，请离开这里抓紧就医！！！如有不明白的地方，请移步： http://www.django-rest-framework.org/tutorial/7-schemas-and-client-libraries/ Schemas是指机器可读的文件，这个文件
复制链接

扫一扫