DRF 接口文档

接口文档

【1】什么是接口文档

• 接口文档（API文档）是描述应用程序编程接口（API）的详细规范。
• 它通常包括API的端点（URLs）、请求方法（GET、POST、PUT、DELETE等）、请求参数、响应格式、错误代码以及其他相关信息。
• 接口文档的主要目的是为开发者提供清晰、一致的指南，以便他们能够正确、高效地与API进行交互。

【2】接口文档的编写形式

• Word或Excel格式：虽然不常见，但某些团队可能选择使用Word或Excel来编写和整理API文档。
• Markdown格式：使用Markdown语法编写文档，简单易懂，易于阅读。很多API文档生成工具都支持Markdown格式。
• 交互式文档：使用专门的API文档工具（如Swagger、Postman等）生成交互式文档，开发者可以直接在文档中测试API，查看实时响应。

【3】使用coreapi

（1）安装导入模块

pip install coreapi

（2）简单使用

• 首先需要路由中配置接口
  • path("docs/", include_docs_urls(title='项目接口'))

from django.contrib import admin
from django.urls import path, include
from rest_framework.documentation import include_docs_urls
urlpatterns = [
    path("admin/", admin.site.urls),
    path("docs/", include_docs_urls(title='项目接口')),
    path("task/", include('task.urls')),
    path("car/", include('car.urls')),
]

• 添加配置信息到setiings文件

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

• 访问地址：http://127.0.0.1:8000/docs/

• 访问样式：

• 测试样式

【4】修改显示样式

（1）视图类上加注释

• 为了使Django REST framework的接口文档更加详细和清晰，我们需要在每个视图类上添加注释。这些注释不仅有助于开发者了解接口的功能和用途，还能自动被coreapi等文档工具解析并生成易于阅读的接口文档。
• 具体来说，我们可以在视图类中添加以下类型的注释：
  1. 接口功能描述：简短地描述该接口的主要功能和作用。
  2. 参数说明：详细列出接口所需的参数，包括参数名称、类型、是否必需、描述以及可能的取值范围或约束条件。
  3. 返回结果：描述接口成功执行后的返回内容，包括返回值的类型、结构以及可能的错误代码或异常信息。

（2）字段介绍help_text

• 在Django的表模型（Model）或Django REST framework的序列化类（Serializer）的字段上，我们可以添加一个help_text属性来为接口文档提供字段的介绍信息。
• 这样做可以帮助开发者更好地了解每个字段的用途、格式要求以及可能的取值范围，从而提高接口的可读性和易用性。

（3）字段必填属性

• 在 Django REST framework 中，当使用 coreapi 来生成接口文档时，字段的 required 属性决定了该字段是否必须出现在请求中。如果字段被标记为 required=True，则它在接口文档中会被标识为必填字段。