GraphQL 中的 API 文档生成实现-JavaScript中文网-JavaScript教程资源分享门户

前言

GraphQL 是一种用于 API 的查询语言及运行时的环境，由 Facebook 在 2012 年开发。相比传统的 RESTful API 体系，GraphQL 具有更高效、更灵活和更易于维护的特点。而 GraphQL 的高效和灵活的跟很大程度上也与其优秀的文档系统相关，可以为前端开发人员提供更好的开发体验。

本文将详细介绍在 GraphQL 中实现 API 文档生成的技术并提供更新维护的指导。

GraphQL API 与文档

在使用 GraphQL API 时，文档是非常重要的一环。GraphQL API 支持的请求参数及其类型、查询语句的格式等，都需要在文档中具体描述以供前端开发人员参考。然而，GraphQL 并没有为 API 文档提供具体实现方法，这就需要我们通过一些手段来实现自己的文档生成器。

实现方法

1.自动文档生成工具

GraphQL 本身并没有提供 API 文档生成方案，然而社区中已经有为 GraphQL API 文档生成器尝试。比如 GraphiQL 就是一个优秀的 GraphQL API 工具，不仅支持 API 的详细查询、运行等，还可以在 UI 端生成 API 的文档、调试等功能。我们可以在 GraphiQL 中运行我们自己所定义的 GraphQL API，然后直接使用 GraphiQL 中生成的 API 文档。而这个方法还有一个好处，就是在开发 GraphQL API 时可以直接在 GraphiQL 中进行 API 的测试。

2.自定义 GraphQL API 文档生成器

如果我们希望具有自定义化的文档生成方案，那么我们可以自己实现 GraphQL API 文档生成器。具体实现方案如下：

// javascriptcn.com 代码示例
import { buildClientSchema, introspectionQuery, printSchema } from "graphql";
import fetch from "node-fetch";

// GraphQL 接口地址
const uri = "http://localhost:3000/graphql";

async function generateDoc() {
  const response = await fetch(uri, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: introspectionQuery
    })
  });
  
  const { data } = await response.json();
  const schema = buildClientSchema(data);
  const types = schema.getTypeMap();

  return printSchema(schema); // 将 schema 结构转化为 Graphql SDL 语言
}

const doc = generateDoc();

export default doc;

在上述代码中，我们首先使用 buildClientSchema() 方法获取 GraphQL API schema 的结构，生成 types 对象。接着，我们需要将 schema 转化为 Graphql SDL 语言的形式，以用于后续的文档生成。最后我们将 GraphQL API 的 schema 生成为文档的形式输出，该文档可以是 Markdown 文档或者其他符合要求的格式，以供前端开发人员使用。

使用指南

我们可以将文档和 API 一起发布在网上。对于 JavaSript 前端底层，文档可以用说明清晰、可读性强的 Markdown 的文档格式。文档中需要列出所有的请求方式、分页、条件查询相关的参数信息以及说明，例如：

# 查询书籍

query { book(id: "001") { id title } }

// javascriptcn.com 代码示例

参数说明：

| 参数名称 | 类型 | 是否必选 | 默认值 | 参数说明 |
| -------- | ---- | -------- | ------ | -------- |
| id       | String | 是 |  | 书名 |

返回值说明：

| 参数名称 | 类型 | 参数说明 |
| -------- | ---- | -------- |
| id       | String | 书籍 id |
| title    | String | 书籍名称 |

在 GraphQL API 上，前端开发人员在 API 文档中看到的参数和类型都是由 schema 定义的，因为在 GraphQL 的 schema 中已经定义了查询方式和参数的类型等详细信息，所以前端人员并不需要进行二次处理，就可以直接理解和使用 API。

总结

GraphQL API 文档的生成可在开发前端项目时为团队提供更好的协作和开发体验。GraphQL 并没有提供默认的 API 文档方案，但我们可以根据自己的需要开发文档生成器，或者基于一些已有的工具来实现 API 文档的生成和维护。在 API 文档的制作过程中应注重代码清晰、文档明确，考虑到前端开发人员的需求，以便于阅读和使用。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/652d3c557d4982a6ebea2af4