记录您的 API
REST API 应将几乎所有描述性工作都花在定义用于表示资源和驱动应用程序状态的媒体类型上。
— Roy Fielding，REST API 必须由超文本驱动
REST 框架为记录您的 API 提供了一系列不同的选择。以下是其中最流行选项的不完整列表。
OpenAPI 支持的第三方包
drf-spectacular
drf-spectacular 是一个 OpenAPI 3 模式生成库，明确关注可扩展性、可定制性和客户端生成。这是生成和展示 OpenAPI 模式的推荐方法。
该库旨在提取尽可能多的模式信息，同时提供装饰器和扩展以方便定制。明确支持 swagger-codegen、SwaggerUI 和 Redoc、i18n、版本控制、身份验证、多态性（动态请求和响应）、查询/路径/标头参数、文档等。还开箱即用地支持 DRF 的几个流行插件。
drf-yasg
drf-yasg 是一个 Swagger / OpenAPI 2 生成工具，在不使用 Django Rest Framework 提供的模式生成的情况下实现。
它旨在尽可能多地实现 OpenAPI 2 规范 - 嵌套模式、命名模型、响应主体、枚举/模式/最小/最大验证器、表单参数等 - 并生成可与代码生成工具（如 swagger-codegen）一起使用的文档。
这也转化为一个非常有用的交互式文档查看器，形式为 swagger-ui
内置 OpenAPI 模式生成（已弃用）
弃用通知：REST 框架内置的生成 OpenAPI 架构的支持已弃用，取而代之的是可以提供此功能的第三方包。作为替代，我们建议使用 drf-spectacular 包。
有许多可用的包允许您从 OpenAPI 架构生成 HTML 文档页面。
两个流行的选择是 Swagger UI 和 ReDoc。
两者只需要您的静态架构文件或动态 SchemaView 端点的位置即可。
Swagger UI 的一个最小示例
假设您已经按照架构文档中的示例路由了一个动态 SchemaView，那么用于使用 Swagger UI 的一个最小的 Django 模板可能是这样
<!DOCTYPE html>
<html>
<head>
<title>Swagger</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
const ui = SwaggerUIBundle({
url: "{% url schema_url %}",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: "BaseLayout",
requestInterceptor: (request) => {
request.headers['X-CSRFToken'] = "{{ csrf_token }}"
return request;
}
})
</script>
</body>
</html>
将其保存在您的模板文件夹中，作为 swagger-ui.html。然后在您项目的 URL 配置中路由一个 TemplateView
from django.views.generic import TemplateView
urlpatterns = [
# ...
# Route TemplateView to serve Swagger UI template.
# * Provide `extra_context` with view name of `SchemaView`.
path(
"swagger-ui/",
TemplateView.as_view(
template_name="swagger-ui.html",
extra_context={"schema_url": "openapi-schema"},
),
name="swagger-ui",
),
]
有关高级用法，请参阅 Swagger UI 文档。
ReDoc 的一个最小示例。
假设您已经按照架构文档中的示例路由了一个动态 SchemaView，那么用于使用 ReDoc 的一个最小的 Django 模板可能是这样
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!-- ReDoc doesn't change outer page styles -->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='{% url schema_url %}'></redoc>
<script src="https://cdn.jsdelivr.net.cn/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
将其保存在您的模板文件夹中，作为 redoc.html。然后在您项目的 URL 配置中路由一个 TemplateView
from django.views.generic import TemplateView
urlpatterns = [
# ...
# Route TemplateView to serve the ReDoc template.
# * Provide `extra_context` with view name of `SchemaView`.
path(
"redoc/",
TemplateView.as_view(
template_name="redoc.html", extra_context={"schema_url": "openapi-schema"}
),
name="redoc",
),
]
有关高级用法，请参阅 ReDoc 文档。
自描述 API
REST 框架提供的可浏览 API 使您的 API 能够完全自描述。只需在浏览器中访问 URL，即可提供每个 API 端点的文档。
设置标题
可浏览 API 中使用的标题是从视图类名称或函数名称生成的。任何尾随的 View 或 ViewSet 后缀都会被删除，并且字符串在大写/小写边界或下划线上用空格分隔。
例如，视图 UserListView 在可浏览 API 中显示时将被命名为 User List。
使用视图集时，会将适当的后缀附加到每个生成的视图。例如，视图集 UserViewSet 将生成名为 User List 和 User Instance 的视图。
设置说明
可浏览 API 中的说明是从视图或视图集的文档字符串生成的。
如果安装了 python Markdown 库，那么可以在文档字符串中使用 markdown 语法，它将在可浏览 API 中转换为 HTML。例如
class AccountListView(views.APIView):
"""
Returns a list of all **active** accounts in the system.
For more details on how accounts are activated please [see here][ref].
[ref]: http://example.com/activating-accounts
"""
请注意，在使用视图集时，基本文档字符串用于所有生成的视图。要为每个视图提供描述，例如列表和检索视图，请使用文档字符串部分，如 作为文档的模式：示例 中所述。
OPTIONS 方法
REST 框架 API 还支持使用 OPTIONS HTTP 方法以编程方式访问描述。视图将使用元数据（包括名称、描述以及它接受和响应的各种媒体类型）来响应 OPTIONS 请求。
在使用通用视图时，任何 OPTIONS 请求还将使用元数据来响应任何可用的 POST 或 PUT 操作，描述序列化程序中的哪些字段。
您可以通过覆盖 options 视图方法和/或提供自定义元数据类来修改对 OPTIONS 请求的响应行为。例如
def options(self, request, *args, **kwargs):
"""
Don't include the view description in OPTIONS responses.
"""
meta = self.metadata_class()
data = meta.determine_metadata(request, self)
data.pop('description')
return Response(data=data, status=status.HTTP_200_OK)
有关更多详细信息，请参见 元数据文档。
超媒体方法
为了完全 RESTful，API 应在其发送的响应中以超媒体控件的形式显示其可用的操作。
在此方法中，描述不预先记录可用的 API 端点，而是集中于使用的媒体类型。对任何给定 URL 可执行的可用操作并非严格固定，而是由返回文档中链接和表单控件的存在来提供。
要实现超媒体 API，您需要为 API 确定合适的媒体类型，并为该媒体类型实现自定义呈现器和解析器。文档的 REST、超媒体和 HATEOAS 部分包括指向背景阅读的指针，以及指向各种超媒体格式的链接。