简介
graphql-document-collector 是一款用于收集 GraphQL 文档语句的 npm 包，可以集成到前端项目中进行文档化 API 建设。在前端开发中，许多时候我们需要针对某个 GraphQL 后端提供的 API 进行文档化，常常需要在代码中手写文档，虽然这是一种简单的方式，但却十分繁琐且容易出错，而 graphql-document-collector 则是解决这个问题的利器。
安装
在使用 graphql-document-collector 之前，我们需要先将其安装到项目中，可以使用 npm 或 yarn 进行安装，安装方式如下：
使用 npm 安装：
# npm 安装 npm install graphql-document-collector
使用 yarn 安装：
# yarn 安装 yarn add graphql-document-collector
使用
下面我们以一个 Vue.js 项目为例，介绍 graphql-document-collector 的基本用法。
引入包
需要在 Vue.js 的 main.js 中引入 graphql-document-collector 包。
import gqlDocCollector from 'graphql-document-collector';
定义 GraphQL API
在项目中，我们定义 GraphQL API 通常是通过 @graphql-tag 包中的 gql 标签来进行的。在定义 GraphQL API 时，将需要文档化的查询语句按照 gql 标签的方式写入到 gql() 函数中。
-- -------------------- ---- -------
------ --- ---- -------------
----- ----------------- - ----
----- ------------------- ---- -
--------- ---- -
--
----
----------
----------
----------- -
--
----
----------
----------
-
-
-
--收集文档
收集文档需要创建一个 Collector 实例，Collector 实例有一个名为 this.collect 的方法，将需要收集的文档语句作为参数传入即可。
-- -------------------- ---- -------
------ --- ---- -------------
------ --------------- ---- -----------------------------
----- -------------- - ----
----- ------------------- ---- -
--------- ---- -
--
----
----------
----------
----------- -
--
----
----------
----------
-
-
-
--
------ ------- -
----- -- -- --
------ ----
---
-------- -
----- --------- -
----- --------- - --- ------------------
----------------------------------
----- ------ - ----- --------------------
------ ---------------
---------- -
--- -----
-
---
---------- - ------------------
-
-
--在 Collector 实例收集完文档后，我们使用 $apollo.query 方法发出 GraphQL 请求就可以获得 GraphQL API 的结果，并将结果绑定到组件中供访问。
查看文档
最后，我们可以通过 Collector 实例上的 toDoc 方法来查看收集的 GraphQL API 文档。
-- -------------------- ---- -------
------ --- ---- -------------
------ --------------- ---- -----------------------------
----- -------------- - ----
----- ------------------- ---- -
--------- ---- -
--
----
----------
----------
----------- -
--
----
----------
----------
-
-
-
--
----- --------- - --- ------------------
----------------------------------
------------------toDoc 方法将会生成如下数据结构的 API 文档：
-- -------------------- ---- -------
-
------ -
--------------- -
---------- -
-
----- -----
------------ ---
----- -----
-
--
----- -
------ -
----------- -
- ----- ----- ------------ --- ----- --------- --
- ----- ------- ------------ --- ----- -------- --
- ----- ------------- ------------ --- ----- -------- --
- ----- ------------- ------------ --- ----- -------- --
-
----- --------------
----- -
----------- -
- ----- ----- ------------ --- ----- --------- --
- ----- ------- ------------ --- ----- -------- --
- ----- ------------- ------------ --- ----- -------- --
- ----- ------------- ------------ --- ----- -------- -
-
-
-
-
-
-
-
-
-结语
graphql-document-collector 是一款十分实用的前端开发工具，通过它我们可以轻轻松松地完成 API 文档化工作，大大提高了开发效率，并减少了出错的机会。希望本文能够帮助您更好地使用该工具。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600671d230d09270238229e4