前言
随着Web API的迅速发展，大量的开发者开始使用OpenAPI规范来描述和文档化他们的API。随着OpenAPI规范的广泛应用，OpenAPI的各种工具库也越来越多。其中，一个非常有用的工具就是openapi-reference-compiler。本文将详细地介绍npm包openapi-reference-compiler的使用教程，包括安装、配置以及实战案例。
安装
使用npm进行安装：
npm install -g openapi-reference-compiler
安装完成后，可以在命令行中使用openapi-reference-compiler命令。
配置
使用openapi-reference-compiler需要一个OpenAPI规范的文件，并且需要定义想要生成文档的部分。例如，下面是一个非常简单的OpenAPI规范文件：
-- -------------------- ---- -------
-------- -----
-----
------ ------ ---
-------- -----
--------
- ---- --------------------------
------
-------
----
-------- --- - ---- -- -----
------------ --------
----------
------
------------ - ---- -- -----
--------
-----------------
-------
----- -----
------
----- ------
-----------
-----
----- ------
----
----- ------在这个规范文件中，我们定义了一个/users的路由，它可以用GET方法请求，请求成功时返回用户的列表。现在我们想要生成文档，具体包含哪些内容呢？我们可以定义一个YAML文件来组织我们的文档配置：
-- -------------------- ---- -------
------- -------
------- ----
----
- ------ ------------
----- ---------------
- ------ -----
----- --------
- ------ --- ---------
----- ----------------
---------
- ------ --- ------
------------ --------在这个配置文件中，我们定义了生成的文档的输出目录，文档的语法类型（可以是Markdown或JSON，本例中我们选择JSON），文档目录树以及文档的具体内容。在这个例子中，我们的文档包含3个部分：Introduction、Usage和API Reference。
在API Reference部分，我们又定义了一个名为GET /users的小节，其中该小节的内容由getUsers操作所定义。
实战
接下来我们将展示一个完整的openapi-reference-compiler应用。现在我们有一个前端应用，需要从后端API获取用户的列表并展示。我们已经有了根据OpenAPI规范文档生成的前端API client，现在我们需要文档化这个client。接下来我们展示如何使用openapi-reference-compiler来生成文档。
步骤一：安装依赖
npm i @openapitools/openapi-generator-cli -g npm i @openapitools/openapi-generator -g npm i @openapitools/openapi-generator-cli -S npm i openapi-reference-compiler -g
步骤二：生成前端API client
利用OpenAPI Generator来生成我们的前端API client：
openapi-generator generate -g typescript-axios -i ./openapi.yaml -o ./client
步骤三：生成文档配置文件
请按照“配置”部分所示的方法，生成文档配置文件。
步骤四：生成文档
openapi-reference-compiler --config ./docs-config.yaml
至此，我们已经成功生成了基于OpenAPI规范的前端API client文档。在完成这个过程之后，我们可以在我们文档配置文件中定义更多的路由并生成更全面的文档。
指导意义
openapi-reference-compiler是一个非常有用的工具，可以帮助前端开发者文档化他们的前端API client。将OpenAPI规范与openapi-reference-compiler相结合，可以让开发者以更高效和规范化的方式文档化他们的前端API client。同时使用这些工具，还可以帮助团队协作和提高代码质量。
示例代码
样例代码存放在我的GitHub中：https://github.com/ChenjieZhou/public/tree/main/nodejs-openapi-docs-compiler-tutorial。
结论
在本文中，我们详细地介绍了如何使用npm包openapi-reference-compiler来生成前端API client文档。我们展示了安装、配置以及具体实例的方式。openapi-reference-compiler是一个非常有用的工具，可以帮助前端开发者更高效和规范化地文档化他们的前端API client。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60056ea181e8991b448e7699