Django REST framework 3.9

3.9 版本允许访问可浏览 API 中的额外操作，引入可组合权限和内置的 OpenAPI 模式支持。(以前称为 Swagger)

资金 (Funding)

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

非常感谢我们所有出色的赞助商，特别是我们的高级支持者，Rover，Sentry，Stream，Auklet，Rollbar，Cadre，Load Impact 和 Kloudless。

内置 OpenAPI 模式支持 (Built-in OpenAPI schema support)

REST framework 现在具有直接包含 OpenAPI 模式支持的第一个通道。(以前称为 Swagger)

确切的说：

• 现在有 OpenAPIRenderer 和 JSONOpenAPIRenderer 类处理将 coreapi.Document 实例编码为 OpenAPI YAML 或 OpenAPI JSON。
• get_schema_view(…) 方法现在默认为 OpenAPI YAML，如果通过 HTTP 内容协商选择 CoreJSON，它将作为次要选项。
• 有一个新的管理命令 generateschema，您可以使用它将模式转储到存储库中。

以下是向 URL conf 添加 OpenAPI 模式的示例：

from rest_framework.schemas import get_schema_view
from rest_framework.renderers import JSONOpenAPIRenderer

schema_view = get_schema_view(
    title='Server Monitoring API',
    url='https://www.example.org/api/',
    renderer_classes=[JSONOpenAPIRenderer]
)

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

下面是如何使用 generateschema 管理命令：

$ python manage.py generateschema --format openapi > schema.yml

您可以使用许多不同的工具来处理 OpenAPI 模式。我们正在研究的一个选项是 API Star 命令行工具。

您可以使用 apistar 来验证您的 API 模式：

$ apistar validate --path schema.json --format openapi
✓ Valid OpenAPI schema.

或者构建 API 文档：

$ apistar docs --path schema.json --format openapi
✓ Documentation built at "build/index.html".

API Star 还包括一个动态客户端库，该库使用 API​​ 模式自动提供客户端库接口以发出请求。

可组合的权限类 (Composable permission classes)

您现在可以使用和/或运算符 ＆ 和 | 来组合权限类。

例如...

permission_classes = [IsAuthenticated & (ReadOnly | IsAdmin)]

如果您使用自定义权限类，那么请确保您从 BasePermission 继承子类来启用此支持。

可浏览 API 中可用的视图集额外操作 (ViewSet Extra Actions available in the Browsable API)

在 v3.8 中引入了 action 装饰器之后，现在可以从可浏览 API 获得视图集上定义的额外动作。

在定义时，会显示 “额外操作” 下拉列表，适当地过滤为详细/非详细操作。

支持的版本 (Supported Versions)

REST framework 3.9 支持 Django 版本 1.11，2.0 和 2.1。

弃用 (Deprecations)

DjangoObjectPermissionsFilter 移动到第三方包 (DjangoObjectPermissionsFilter moved to third-party package.)

DjangoObjectPermissionsFilter 类是等待弃用，将在 3.10 中弃用并在 3.11 中完全删除。

它已被转移到第三方 djangorestframework-guardian 包。请改用它。

路由器参数/方法重命名为使用 basename 以保持一致性 (Router argument/method renamed to use basename for consistency.)

• 已重命名 Router.register base_name 参数以 basename 取代。
• 已重命名 Router.get_default_base_name 方法以 Router.get_default_basename 取代。见 #5990。

base_name 和 get_default_base_name() 正在等待弃用。它们将在 3.10 中被弃用，并在 3.11 中被完全删除。

action 装饰器替换 list_route 和 detail_route (action decorator replaces list_route and detail_route)

list_route 和 detail_route 现在被弃用以单个 action 装饰器取代。它们将在 3.10 完全删除。

action 装饰器采用布尔 detail 参数。

• 使用 @action(detail=True) 替换 detail_route。
• 使用 @action(detail=False) 替换 list_route。

exclude_from_schema

现在已删除了 @api_view 的 APIView.exclude_from_schema 和 exclude_from_schema 参数。

对于 APIView，您应该在视图类上设置 schema = None 属性。

对于基于函数的视图，可以使用 @schema 装饰器将视图从模式中排除，方法是使用 @schema(None)。

小修正和改进 (Minor fixes and improvements)

此版本中有大量小修正和改进。有关完整列表，请参阅发行说明页面。

What's next

我们计划迭代​​地将 OpenAPI 转变为标准模式表示。这意味着 coreapi 依赖关系将逐渐被删除，我们将直接生成模式，而不是构建 CoreAPI Document 对象。

OpenAPI 显然已成为指定 Web API 的标准，因此在我们的模式无关的文档模型中不再有什么价值。进行此更改意味着我们可以更轻松地利用全套 OpenAPI 功能。

这也将使更广泛的工具可用。

我们将重点继续开发 API Star 库和客户端工具，使之成为生成 API 文档、验证 API 模式和提供动态客户端库的推荐选项。

关于 ASGI 格局的成熟方面，还有大量正在进行的工作，其中一些工作最终可能会反馈到 Django。

在 Uvicorn 网站服务器上将有进一步的工作，以及为 Starlette 网页框架计划的许多功能，该框架正在构建与 ASGI 一起工作的基础工具集。