Django REST framework 3.6

Django REST framework 3.6

3.6 版本为 REST framework 增加了两个主要的新功能。

内置交互式 API 文档支持。
新的 JavaScript 客户端库。

上图：交互式 API 文档。

资金 (Funding)

如果没有 Mozilla 对项目的支持以及我们的合作资金模式，3.6 版本是不可能实现的。

如果您在商业上使用 REST framework，并且希望看到这项工作继续进行，我们强烈鼓励您通过注册付费计划来投资其持续开发。

非常感谢我们所有的赞助商，特别是我们的高级支持者 Rover，Sentry，Stream，Machinalis，Rollbar 和 MicroPyramid。

交互式 API 文档 (Interactive API documentation)

REST framework 的新 API 文档支持许多功能：

实时 API 交互。
支持各种身份验证方案。
Python、JavaScript 和命令行客户端的代码片段。

coreapi 库作为 API 文档的依赖关系是必需的。确保安装最新版本 (2.3.0 或以上)。pygments 和 markdown 库是可选的，但建议使用。

要安装 API 文档，您需要将其包含在您的项目 URLconf 中：

from rest_framework.documentation import include_docs_urls
API_TITLE = 'API title'
API_DESCRIPTION = '...'
urlpatterns = [
    ...
    url(r'^docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION))
]

一旦安装完毕，您会看到一些像这样的东西：

Django REST framework 3.6 - 图8

在接下来的几周里，我们可能会对 API 文档进行进一步的改进。请记住，这是一个新特性，如果您遇到任何问题或限制，请给我们反馈。

有关记录 API 端点的详细信息，请参阅 “记录 API” 部分。

JavaScript 客户端库 (JavaScript client library)

JavaScript 客户端库允许您加载 API 模式，然后在应用层接口上与该 API 交互，而不是显式地构造 fetch 请求。

这里有一个简单的示例来演示：

加载客户端库和模式。
实例化经过身份验证的客户端。
使用客户端发出 API 请求。

index.html

<html>
    <head>
        <script src="/static/rest_framework/js/coreapi-0.1.0.js"></script>
        <script src="/docs/schema.js"></script>
        <script>
            const coreapi = window.coreapi
            const schema = window.schema
            // 实例化客户端...
            let auth = coreapi.auth.TokenAuthentication({scheme: 'JWT', token: 'xxx'})
            let client = coreapi.Client({auth: auth})
            // 发出 API 请求...
            client.action(schema, ['projects', 'list']).then(function(result) {
                alert(result)
            })
        </script>
    </head>
</html>

JavaScript 客户端库支持各种身份验证方案，可以由项目本身使用，也可以作为与 API 交互的外部客户端使用。

客户端不限于使用 REST framework API，尽管它目前仅支持加载 CoreJSON API 模式。计划支持 Swagger 和其他 API 模式。

有关更多详细信息，请参阅 JavaScript 客户端库文档。

Python 客户端库的身份验证类 (Authentication classes for the Python client library)

Python 客户端库中以前的身份验证支持仅限于允许用户提供显式标头值。

通过引入 BasicAuthentication、TokenAuthentication 和 SessionAuthentication 方案，我们现在可以更好地支持处理身份验证的细节。

您可以在实例化新客户端时包含身份验证方案。

auth = coreapi.auth.TokenAuthentication(scheme='JWT', token='xxx-xxx-xxx')
client = coreapi.Client(auth=auth)

有关更多信息，请参阅 Python 客户端库文档。

弃用 (Deprecations)

更新 coreapi (Updating coreapi)

如果您正在使用 REST framework 的模式生成，或者想要使用 API 文档，那么您需要更新到最新版本的 coreapi。(2.3.0)

从路由器生成模式 (Generating schemas from Router)

3.5 版本用于生成模式视图的路由器参数 (例如 schema_title，schema_url 和 schema_renderers) 的 “等待弃用” 现在已升级为 “弃用” 警告。

您应该使用 get_schema_view() 函数，而不是使用 DefaultRouter(schema_title='Example API')，并在 URL conf 中显式包含视图。

DjangoFilterBackend

3.5 版本内置的 DjangoFilterBackend “等待弃用” 警告现已升级为 “弃用” 警告。

您应该更改您的导入和 REST framework 过滤器设置如下：

rest_framework.filters.DjangoFilterBackend 变为 django_filters.rest_framework.DjangoFilterBackend。
rest_framework.filters.FilterSet 变为 django_filters.rest_framework.FilterSet。

What’s next

在未来几周内，API 文档和 JavaScript 客户端库可能会有一些改进，其中可能包括以下部分：

支持私有 API 文档，需要登录。
JavaScript 客户端和 API 文档中的文件上载和下载支持。
JavaScript 客户端库的综合文档。
自动在 API 文档代码段中包含身份验证详细信息。
在命令行客户端中添加身份验证支持。
支持在 JavaScript 客户端中加载 Swagger 和其他模式。
改进了对记录参数模式和响应模式的支持。
完善 API 文档交互模式。

一旦这些改进工作完成，我们将开始实时支持 3.7 版本的特性工作。