在 GraphQL 中，schema 是一个非常重要的概念。它定义了一个 GraphQL API 中所有的可用类型、查询和变量，并且也是前端开发中常常需要用到的动态 API 查询方法。
一个好的 GraphQL schema 不仅可以让 API 使用者更好地理解 API 的功能和数据结构，还可以节约 API 开发者的时间和精力。而在 GraphQL 中，可以通过利用 schema 注释来生成易于理解和阅读的文档。
本文将详细介绍如何在 GraphQL 中利用 schema 注释生成文档，并提供示例代码和指导意义。
什么是 schema 注释
在 GraphQL 中，schema 的定义通常是以 SDL (Schema Definition Language) 格式编写的，它描述了所有可用的类型、查询和变量。
而 schema 注释则是一种特殊的注释方式，它被用来描述 schema 的各个部分，以帮助开发者和 API 使用者更好地理解 API 的结构和功能。
在 GraphQL 中，schema 注释可以通过在 SDL 中使用双引号 " 来定义，参考如下示例：
-- -------------------- ---- ------- --- ----------------------- --- ---- ---- - --- --- ------------------- ---- ------ --------- ----- ------- ------- ----- ------- ---- --- - --- --------- --- ---- ----- - --- ---------- --- ------ ------ -
在上面的示例中，我们可以看到两个类型定义被定义了注释，分别是 User 和 Query。他们的注释标注了这两个类型的用途和结构，从而更好地帮助 API 使用者理解和使用。
利用 schema 注释生成文档
在 GraphQL 中，我们可以通过在 schema 注释中定义一些特殊的标识符，来帮助文档生成工具更加精确地理解和生成文档。
以下是一些常用的 schema 注释标识符：
""" … """：定义类型、字段、参数的说明文本。@deprecated(reason: STRING)：用于标记废弃的字段或类型。通常配合reason参数一起使用，用于说明废弃原因。@unique：用于标明某个字段的唯一性。@relation(name: STRING, direction: STRING, from: STRING, to: STRING)：用于标记两个类型之间的关系。@auth(rules: [AuthRule]!)：用于标记该字段或类型的权限要求，具体规则可以在AuthRule类型中定义。
通过在 schema 注释中使用这些标识符，我们可以帮助文档生成工具更加准确地生成文档，提高文档的可读性和易用性。
例如，使用 graphql-tools 插件中的 makeExecutableSchema 函数来创建 schema 时，可以通过设置 resolverValidationOptions 为 requireResolversForResolveType: 'ignore'"，来忽略对未定义字段的警告。然后，通过使用 swagger-jsdoc 插件来生成文档：
-- -------------------- ---- -------
----- ------- - -------------------
----- --------- - ------------------------------
----- ------------ - -------------------------
----- - -------------------- - - -------------------------
----- -------- - -
---
----
---
---- ---- -
---
-- ---------------- ---- -----
---
--- --- ------------------- ---- ------ ---------
---
--------------
---
----- ------- -------
---
----
---
----- -------
---
----
---
---- ---
-
---
----
---
---- ----- -
---
------
---
------ ------
-
--
----- ------ - ---------------------- --------- -------------------------- - ------------------------------- -------- - ---
----- ------- - -
----------- -
-------- --------
----- -
------ ----- -----
-------- -------
--
-------- -
- ---- --------------------------- -
-
--
----- -----------------
--
----- ----------- - ----------------------
----- --- - ----------
-------------------- ---------------- ------------------------------通过使用 swagger-jsdoc 插件，我们可以生成如下的 API 文档：
总结
在 GraphQL 中，利用 schema 注释是一种非常有效的方式来生成易于理解和阅读的 API 文档。通过合理地使用 schema 注释标识符，API 使用者可以更好地理解和使用 API，API 开发者也可以更高效地开发和维护 API。
希望本文提供的方法和示例可以帮助到你，让你更好地使用 GraphQL。如果你有任何疑问或建议，欢迎留言或联系我！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64fc14aff6b2d6eab3205fcb