Django Ninja 中如何为查询参数添加文档描述

在 Django Ninja 框架中，为 API 接口的查询参数添加详细的文档描述是一个常见的需求。本文将详细介绍如何通过 Schema 类和 Annotated 类型来为查询参数添加标题、示例和描述信息，使生成的 API 文档更加清晰和专业。

基本实现方法

Django Ninja 提供了 Schema 类来定义请求参数的结构，结合 Python 的 Annotated 类型和 Field 类，我们可以为每个参数添加丰富的元数据信息：

from ninja import Query, Schema
from typing import Annotated
from pydantic import Field

class MyQueryParams(Schema):
    device_id: str
    start: Annotated[
        int,
        Field(
            title="起始时间",
            examples=[1625097600000],
            description="时间范围的开始时间戳(毫秒), UTC时区",
        ),
    ]
    end: Annotated[
        int,
        Field(
            title="结束时间",
            examples=[1625184000000],
            description="时间范围的结束时间戳(毫秒), UTC时区",
        ),
    ]

实际应用示例

定义好参数 Schema 后，可以在 API 视图中使用它：

@api.get("/events")
def get_events(request, params: Query[MyQueryParams]):
    """
    获取设备事件
    
    参数:
    - params: 查询参数，包含设备ID和时间范围
    """
    return {"events": query_events(params.device_id, params.start, params.end)}

文档生成效果

使用上述方法定义的查询参数会在自动生成的 API 文档中显示如下信息：

1. 每个参数的名称和类型
2. 通过 title 指定的自定义标题
3. 通过 description 提供的详细说明
4. 通过 examples 给出的使用示例

最佳实践建议

1. 保持一致性：为所有接口的查询参数都添加文档描述，保持项目文档风格统一
2. 详细说明：对特殊格式的参数(如时间戳)要注明单位和时区信息
3. 提供示例：为复杂参数提供典型值示例，帮助开发者快速理解
4. 分层设计：对于多个接口共用的参数，可以提取为基类 Schema 复用

通过这种方式，开发者可以轻松地为 Django Ninja 项目生成专业、清晰的 API 文档，大大提升项目的可维护性和开发者体验。