django Rest Framework 系列 7 - Schemas & client libraries

向右看齐 2022-06-17 05:25 94阅读 0赞

官方地址： [http://www.django-rest-framework.org/tutorial/7-schemas-and-client-libraries/][http_www.django-rest-framework.org_tutorial_7-schemas-and-client-libraries]

一个Schemas是一种机器可读文档,用于描述可用的API端, URLS 以及支持的操作。  
Schemas可以是自动生成文档的有用工具, 也可以用于驱动与API进行交互的动态客户端库。

**1. Core API**  
为了提供 schemas 支持, REST框架使用核心API(Core API)  
Core API 是一个描述API的文档规范, 它用来提供可用内部标识合适以及暴露可交互的API，既可以用于服务端，也可用户客户端。  
当用于服务端时, Core API 允许API支持各种模式或超媒体格式的渲染。  
当用于客户端时, Core API 允许动态驱动客户端库, 可以与服务端暴露的支持的模式或超媒体格式的API进行交互

**2. 添加模式(schema)**  
REST框架支持明确定义的模式视图或自动生成的模式。 由于我们使用的是视图和路由器，我们可以简单地使用自动模式生成。  
为了能包含一个API模式，你需要安装`coreapi` 包

$ 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的根路径，你会看到`corejson` 为可用的选项  
![这里写图片描述][SouthEast]

我们还可以在命令行模式下请求schema, 需要在`Accept` 头中指定希望返回的内容类型

$ 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 编码输出  
也支持其它模式格式，比如 `Open API`

**2. 使用命令行客户端**  
现在我们的API展现了一个模式端,我们可以使用一个动态的客户端库与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)
        }

我们还没有进行认证,所以现在我们只能看到只读信息, 这与我们如何设置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 端需要命名参数。要获取特定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>
      ...

**3. 客户端认证**  
如果我们想要创建、编辑和删除 snippet, 我们需要认证为可用用户。本案中我们仅使用基本认证。  
确保替换`<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)
        }

现在我们可以使用这些点进行交互, 比如，创建一个新的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进行交互。 Python客户端库是第一个可用的，并且计划即将发布一个Javascript客户端库。  
有关定制 schema 生成和使用Core API客户端库的更多详细信息，您需要参考完整的文档。

**回顾**  
我们现在拥有一个非常少量的代码，它具有完整的Web浏览器，可以完全可浏览Web API，包括一个模式驱动的客户端库，并且具有身份验证，每个对象权限和多个渲染器格式。

我们已经走过了设计过程的每个步骤，并且看到如果我们慢慢努力，可以简单地使用常规的Django视图自定义任何事情。

[http_www.django-rest-framework.org_tutorial_7-schemas-and-client-libraries]: http://www.django-rest-framework.org/tutorial/7-schemas-and-client-libraries/
[SouthEast]: /images/20220617/1d4eadd0b5b348ea8e0ba67f74638bf9.png