Documenting your API

记录您的 API (Documenting your API)

REST API 应该花费几乎所有的描述性工作来定义用于表示资源和驱动应用程序状态的媒体类型。—— Roy Fielding, REST APIs must be hypertext driven

REST framework 提供对 API 文档的内置支持。还有一些很棒的第三方文档工具可用。

内置 API 文档 (Built-in API documentation)

内置的 API 文档包括：

• API 端点的文档。
• 为每个可用的 API 客户端库自动生成代码示例。
• 支持 API 交互。

安装 (Installation)

coreapi 库是 API 文档的必需品。确保安装最新版本。pygments 和 markdown 库是可选的，但推荐使用。

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

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    url(r'^docs/', include_docs_urls(title='My API title'))
]

这将包括两个不同的视图：

• /docs/ - 文档页面本身。
• /docs/schema.js - 公开 API 模式的 JavaScript 资源。

---

注意：默认情况下，include_docs_urls 配置底层 SchemaView 以生成公共模式。这意味着视图不会使用 request 实例进行实例化。即在视图内部 self.request 将为 None。

要与检查 self.request 的行为方法 (例如 get_serializer 或 get_serializer_class 等) 兼容，或者特别是 self.request.user 可能需要调整以处理这种情况。

您可以通过使用 public = False 调用 include_docs_urls 来确保为 request 实例提供视图：

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    # 使用有效的`request`实例生成模式：
    url(r'^docs/', include_docs_urls(title='My API title', public=False))
]

---

记录您的视图 (Documenting your views)

您可以通过包含描述每个可用操作的文档字符串来记录您的视图。例如：

class UserList