您的位置: 首页  >  文章  >  3.5 Announcement

3.5 Announcement

分类: 文章 • 2022-10-30 15:56:18

Django REST framework 3.5

3.5 版本是计划系列中的第二个版本，它处理模式生成，超媒体支持，API 客户端库以及最终的实时支持。

资金 (Funding)

如果没有我们的合作资助模式，3.5 版本是不可能实现的。如果您在商业上使用 REST framework，并且希望看到这项工作继续进行，我们强烈鼓励您通过注册付费计划来投资其持续开发。

3.5 Announcement 3.5 Announcement 3.5 Announcement 3.5 Announcement

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

改进了模式生成 (Improved schema generation)

视图上的文档字符串现在被引入模式定义，允许您使用模式定义来记录 API。

现在还有一个快捷函数 get_schema_view()，它使向 API 添加模式视图变得更容易。

例如，要将 swagger 模式包含到您的 API 中，您可以执行以下操作：

  • 运行 pip install django-rest-swagger。
  • 将 'rest_framework_swagger' 添加到 INSTALLED_APPS 设置中。
  • 在 URL conf 中包括模式视图：
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer

schema_view = get_schema_view(
    title='Example API',
    renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer]
)

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

对模式生成进行了大量修复。这些应解决任何使用 django-rest-swagger 包的最新版本的人的问题。

其中一些更改确实会影响生成的模式结构，因此如果您已经使用了模式生成，那么您应该确保检查弃用说明，特别是如果您当前正在使用动态客户端库与 API 进行交互。

最后，我们还将模式生成作为公开文档化的 API 公开，允许您更容易地覆盖该行为。

请求测试客户端 (Requests test client)

您现在可以使用 requests 库测试项目。

这将公开与使用标准请求会话实例完全相同的接口。

client = RequestsClient()
response = client.get('http://testserver/users/')
assert response.status_code == 200

这个接口不会向网络发送任何 HTTP 请求，而是将所有发出的请求强制放入 WSGI，并直接调用应用程序。

Core API client

您现在还可以使用 coreapi 客户端库通过与项目交互来测试项目。

# 获取 API 模式
client = CoreAPIClient()
schema = client.get('http://testserver/schema/')

# 创建新组织
params = {'name': 'MegaCorp', 'status': 'active'}
client.action(schema, ['organisations', 'create'], params)

# 确保该组织存在于列表中
data = client.action(schema, ['organisations', 'list'])
assert(len(data) == 1)
assert(data == [{'name': 'MegaCorp', 'status': 'active'}])

同样，这将使用 WSGI 接口直接调用应用程序，而不是进行实际的网络调用。

如果您计划使用 coreapi 客户端库或其他一些自动生成的客户端主要与您的 API 进行交互，那么这是一个不错的选择。

实时测试 (Live tests)

requests 客户端和 coreapi 客户端都有一个有趣的方面，即它们允许您以这样一种方式编写测试，即它们也可以针对实时服务运行。

通过将基于 WSGI 的客户端实例切换到 requests.Session 或 coreapi.Client 的实际实例，您可以让测试用例进行实际的网络调用。

能够编写可以训练您的临时或生产环境的测试用例是一个强有力的工具。但是，为了做到这一点，您需要密切关注如何处理设置和拆卸，以确保将测试数据与其他实时或临时数据严格隔离。

RAML support

我们现在已经初步支持 RAML 文档生成。

3.5 Announcement

计划进一步开展编码和文档生成工作，以便在以后提供诸如 “立即尝试” 支持等功能。

此工作现在还意味着您可以使用 Core API 客户端库与公开 RAML 规范的 API 进行交互。

RAML 编解码器给出了一些以这种方式与 Spotify API 交互的示例。

验证码 (Validation codes)

REST framework 引发的异常现在包括短代码标识符。当与我们的自定义错误处理一起使用时，现在允许您修改 API 错误消息的样式。

作为示例，这允许以下错误响应的样式：

{
    "message": "You do not have permission to perform this action.",
    "code": "permission_denied"
}

这对于验证错误特别有用，验证错误使用适当的代码来识别不同类型的失败…

{
    "name": {"message": "This field is required.", "code": "required"},
    "age": {"message": "A valid integer is required.", "code": "invalid"}
}

客户端上传和下载支持 (Client upload & download support)

Python coreapi 客户端库和 Core API 命令行工具现在都完全支持文件上传和下载。

弃用 (Deprecations)

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

用于生成模式视图的路由器参数 (例如 schema_title) 在正在等待弃用。

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

确保在路由器 url 之前包含视图。例如：

from rest_framework.schemas import get_schema_view
from my_project.routers import router

schema_view = get_schema_view(title='Example API')

urlpatterns = [
    url('^$', schema_view),
    url(r'^', include(router.urls)),
]

模式路径表示 (Schema path representations)

模式路径中的 'pk' 标识符现在默认映射到实际的模型字段名。这通常是 'id'。

这为模式提供了更好的外部表示，减少了暴露实现细节。它还反映了使用带有 fields = '__all__' 的 ModelSerializer 类的行为。

您可以通过在 REST framework 设置中设置 'SCHEMA_COERCE_PATH_PK': False 来恢复到以前的行为。

模式操作名称表示 (Schema action name representations)

内部 retrieve() 和 destroy() 方法名现在强制为 read 和 delete 的外部表示。

您可以通过在 REST framework 设置中设置 'SCHEMA_COERCE_METHOD_NAMES': {} 来恢复到以前的行为。

DjangoFilterBackend

内置的 DjangoFilterBackend 的功能现在完全包含在 django-filter 包中。

您应该更改导入和 REST framework 筛选器设置，如下所示：

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

现有的导入将继续有效，但现在正在等待弃用。

CoreJSON 媒体类型 (CoreJSON media type)

CoreJSON 的媒体类型现在是 application/json+coreapi，而不是以前的 application/vnd.json+coreapi。这使得它更符合其他自定义媒体类型，比如 Swagger 和 RAML 所使用的那些类型。

客户端目前接受任何一种媒体类型。旧的样式媒体类型将在以后被废弃。

ModelSerializer ‘fields’ and ‘exclude’

ModelSerializer 和 HyperlinkedModelSerializer 必须包含字段选项或排除选项。fields = '__all__' 快捷方式可用于显式地包含所有字段。

如果没有设置 fields 或 exclude 字段，将在 3.3 版本中引发等待弃用警告，并在 3.4 中引发弃用警告。

后记

Django REST framework 中文版系列文章是本人从官方网站文档学习时根据 Google 翻译 + 自己理解的成果，本人能力有限，如有翻译不当之处，欢迎讨论。

Github 地址：Django REST framework 中文文档
本人博客：Home - Django REST framework

相关推荐