3.9 版本允许访问可浏览 API 中的额外操作,引入可组合权限和内置的 OpenAPI 模式支持。(以前称为 Swagger)
如果您在商业上使用 REST framework,并且希望看到这项工作继续进行,我们强烈鼓励您通过注册付费计划来投资其持续开发。
非常感谢我们所有出色的赞助商,特别是我们的高级支持者,Rover,Sentry,Stream,Auklet,Rollbar,Cadre,Load Impact 和 Kloudless。
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 模式自动提供客户端库接口以发出请求。
您现在可以使用和/或运算符 &
和 |
来组合权限类。
例如...
permission_classes = [IsAuthenticated & (ReadOnly | IsAdmin)]
如果您使用自定义权限类,那么请确保您从 BasePermission
继承子类来启用此支持。
在 v3.8 中引入了 action
装饰器之后,现在可以从可浏览 API 获得视图集上定义的额外动作。
在定义时,会显示 “额外操作” 下拉列表,适当地过滤为详细/非详细操作。
REST framework 3.9 支持 Django 版本 1.11,2.0 和 2.1。
DjangoObjectPermissionsFilter
类是等待弃用,将在 3.10 中弃用并在 3.11 中完全删除。
它已被转移到第三方 djangorestframework-guardian
包。请改用它。
- 已重命名
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 中被完全删除。
list_route
和 detail_route
现在被弃用以单个 action
装饰器取代。它们将在 3.10 完全删除。
action
装饰器采用布尔 detail
参数。
- 使用
@action(detail=True)
替换detail_route
。 - 使用
@action(detail=False)
替换list_route
。
现在已删除了 @api_view
的 APIView.exclude_from_schema
和 exclude_from_schema
参数。
对于 APIView
,您应该在视图类上设置 schema = None
属性。
对于基于函数的视图,可以使用 @schema
装饰器将视图从模式中排除,方法是使用 @schema(None)
。
此版本中有大量小修正和改进。有关完整列表,请参阅发行说明页面。
我们计划迭代地将 OpenAPI 转变为标准模式表示。这意味着 coreapi
依赖关系将逐渐被删除,我们将直接生成模式,而不是构建 CoreAPI Document
对象。
OpenAPI 显然已成为指定 Web API 的标准,因此在我们的模式无关的文档模型中不再有什么价值。进行此更改意味着我们可以更轻松地利用全套 OpenAPI 功能。
这也将使更广泛的工具可用。
我们将重点继续开发 API Star 库和客户端工具,使之成为生成 API 文档、验证 API 模式和提供动态客户端库的推荐选项。
关于 ASGI 格局的成熟方面,还有大量正在进行的工作,其中一些工作最终可能会反馈到 Django。
在 Uvicorn 网站服务器上将有进一步的工作,以及为 Starlette 网页框架计划的许多功能,该框架正在构建与 ASGI 一起工作的基础工具集。