Huma框架中如何为OpenAPI文档添加查询参数

在使用Huma框架开发RESTful API时，我们经常需要实现分页功能。一个常见的做法是在URL中使用查询参数(如page和size)来控制分页行为。然而，默认情况下这些参数不会自动出现在生成的OpenAPI文档中。

问题背景

Huma是一个基于Go语言的API框架，它能够自动生成OpenAPI规范文档。当我们在路由处理函数中使用中间件(如chi的Paginate中间件)来处理分页参数时，虽然功能可以正常工作，但这些参数不会自动出现在API文档中。

解决方案

要让查询参数出现在OpenAPI文档中，我们需要在注册路由时显式声明这些参数。具体做法是在huma.Operation结构中添加Parameters字段：

huma.Register(api, huma.Operation{
    OperationID: "get-stuff",
    Summary:     "Gets all stuff",
    Method:      http.MethodGet,
    Path:        "/stuff",
    Parameters: []*huma.Param{
        {
            Name:        "page",
            In:          "query",
            Description: "The page number to retrieve",
            Required:    false,
        },
        {
            Name:        "size",
            In:          "query",
            Description: "The number of items per page",
            Required:    false,
        },
    },
}, handlers.GetAllStuff)

进阶技巧

如果项目中多个路由都需要相同的分页参数，可以创建一个辅助函数来简化操作：

func WithPagination(op huma.Operation) huma.Operation {
    op.Parameters = append(op.Parameters, []*huma.Param{
        {
            Name:        "page",
            In:          "query",
            Description: "The page number to retrieve",
            Required:    false,
        },
        {
            Name:        "size",
            In:          "query",
            Description: "The number of items per page",
            Required:    false,
        },
    }...)
    return op
}

然后可以这样使用：

huma.Register(api, WithPagination(huma.Operation{
    OperationID: "get-stuff",
    Summary:     "Gets all stuff",
    Method:      http.MethodGet,
    Path:        "/stuff",
}), handlers.GetAllStuff)

最佳实践

1. 保持一致性：在整个API中使用相同的分页参数名称(如page和size)

2. 提供默认值：在文档中说明参数的默认值，或者在中间件中设置合理的默认值

3. 参数验证：考虑添加参数验证，如限制size的最大值

4. 文档完整性：确保所有通过中间件处理的参数都在OpenAPI文档中有相应声明

通过这种方式，我们既保持了代码的简洁性，又确保了API文档的完整性，为API使用者提供了清晰的接口说明。