如何向“GraphQL 模式语言”中的字段添加描述答案

【问题标题】：如何向“GraphQL 模式语言”中的字段添加描述
【发布时间】：2017-02-19 03:30:30
【问题描述】：

我有一个 graphql 架构，其中的一个片段如下所示：

type User {
    username: String!
    password: String!
}

在 graphiql 中，有一个描述字段，但它总是说“自我描述”。如何向架构添加描述？

【问题讨论】：

PS 哈希你的密码孩子们！

标签： javascript graphql apollo-server

【解决方案1】：

如果您使用的是 GraphQL.js 版本 0.7.0 或更高版本，您可以直接在要描述的字段、类型或参数之前添加注释。例如：

# A type that describes the user
type User {
     # The user's username, should be typed in the login field.
     username: String!
     # The user's password.
     password: String!
}

在 0.7.0 版本以下，无法在架构语言中添加描述。

更新：从 v0.12.3 版本开始，您应该使用 string literals

"""
A type that describes the user. Its description might not 
fit within the bounds of 80 width and so you want MULTILINE
"""
type User {
     "The user's username, should be typed in the login field."
     username: String!
     "The user's password."
     password: String!

}

【讨论】：

这不再是默认值，请参阅：github.com/graphql/graphql-js/blob/master/src/utilities/… -- 应该是类似"My description"的字符串文字
所以字符串文字是 2018 年 2 月的当前默认值。
规范的相关部分：graphql.github.io/graphql-spec/June2018/#sec-Descriptions
如果有人正在寻找如何在 TypeGraphQL 中执行此操作，只需在装饰器选项中使用 description 属性。例如。 @ObjectType({description:'Here'})。 @Field({description:...}, @Arg and @Query也一样

【解决方案2】：

这是一个很好的问题！实际上在graphqlworld 有着悠久的历史。

graphql-js 存储库上有多个问题、讨论和拉取请求，试图讨论可能的语法，因为许多社区成员认为这是必要的。感谢 Lee Byron 和 this Pull Request，我们实际上可以使用传统的 cmets 向模式语言添加描述。

例如，

// Grab some helpers from the `graphql` project
const { buildSchema, graphql } = require('graphql');

// Build up our initial schema
const schema = buildSchema(`
schema {
  query: Query
}

# The Root Query type
type Query {
  user: User
}

# This is a User in our project
type User {
  # This is a user's name
  name: String!

  # This is a user's password
  password: String!
}
`);

而且，如果我们使用比0.7.0 更新的graphql，那么 cmets 实际上会变成字段或类型的描述。我们可以通过在我们的架构上运行自省查询来验证这一点：

const query = `
{
  __schema {
    types {
        name
        description,
        fields {
            name
            description
        }
    }
  }
}
`;

graphql(schema, query)
  .then((result) => console.log(result));

这会给我们一个看起来像这样的结果：

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "User",
          "description": "This is a User in our project",
          "fields": [
            {
              "name": "name",
              "description": "This is a user's name"
            },
            {
              "name": "password",
              "description": "This is a user's password"
            }
          ]
        },
      ]
    }
  }
}

并向我们展示了# cmets 被合并为我们放置它们的字段/cmets 的描述。

希望有帮助！

【讨论】：

非常有帮助的谢谢 - 我确实搜索了很长时间的答案，并且正在努力解决许多老问题 - 当答案如此简单时！ :)
是的，我也花了一段时间才找到。 TYVM！
我使用的是 graphql 0.12.3，这对我不起作用。使用上面的代码，描述始终为空。

【解决方案3】：

如果您使用的是 Java 实现 ....

对于采用模式优先方法的graphql-java 7.0 版（撰写本文时的最新版本），您可以在字段、类型或参数上方使用cmets。

字符串文字在 7.0 版中是不有效的语法。

【讨论】：