能否为GraphQL查询参数添加描述或格式注释？

当然可以！你之前把参数说明塞进字段描述里的做法其实没必要——GraphQL本身就支持给查询参数单独添加描述/注释，这样在GraphiQL里点击参数就能直接看到格式说明啦，我给你分两种常见的场景讲讲具体怎么实现：

1. 用SDL（Schema定义语言）写Schema时 #

这是最直接的方式，你可以在参数前用单行注释#，或者多行注释""" """来添加说明，示例如下：

type Query {
  getPosts(
    # yyyy/mm/dd格式的字符串，用于筛选发布日期大于等于该值的内容
    from_date: String!
    # 可选参数，yyyy/mm/dd格式的字符串，用于筛选发布日期小于等于该值的内容
    to_date: String
  ): [Post!]!
}

写完之后，在GraphiQL里点击from_date参数，就能直接看到你写的格式说明，完全符合你的需求。

2. 代码优先的开发模式（比如Apollo Server、TypeGraphQL） #

如果是用JS/TS通过代码生成Schema，不同框架有对应的配置方式：

Apollo Server（JavaScript） #

在gql模板字符串里同样可以加注释，和SDL写法一致：

const typeDefs = gql`
  type Query {
    getPosts(
      # yyyy/mm/dd格式的字符串，起始筛选日期
      from_date: String!
      # 可选，yyyy/mm/dd格式的字符串，结束筛选日期
      to_date: String
    ): [Post!]!
  }
`;

TypeGraphQL（TypeScript） #

可以通过@Arg装饰器的description属性来指定参数说明：

@Query(() => [Post])
getPosts(
  @Arg("from_date", { description: "yyyy/mm/dd格式的字符串，起始筛选日期" }) fromDate: string,
  @Arg("to_date", { description: "可选，yyyy/mm/dd格式的字符串，结束筛选日期", nullable: true }) toDate?: string,
) {
  // 业务逻辑处理
}

这样做的好处是参数说明和字段描述完全分离，结构更清晰，GraphiQL会自动读取这些注释并展示在参数详情面板里，完美解决你遇到的问题。

内容的提问来源于stack exchange，提问作者Timmy