引言
在前端开发中，我们常常需要与后端对接 API 接口，对于 API 接口的定义和文档编写是很重要的一环。而 Swagger 是一种用于描述 API 接口的规范，提供了一种通用的语言和工具来描述、定义、调用和可视化 RESTful API 接口。
在这篇文章中，我们将介绍 npm 包 api2swagger-ext 的使用教程。api2swagger-ext 是一个可以将 API 接口转换成 Swagger 规范的工具，支持多种语言和框架。本教程将介绍如何使用 api2swagger-ext 将 Express 框架的 API 接口转换成 Swagger 规范。
安装
使用 npm 包管理器进行安装：
npm install api2swagger-ext --save-dev
使用方法
1. 创建 Express API 接口
首先我们需要创建一个简单的 Express API 接口。例如，我们可以创建一个 /users 路径，用于获取用户信息：
-- -------------------- ---- -------
----- ------- - -------------------
----- --- - ----------
----------------- ----- ---- -- -
-----------
--- --
----- ----
-- -
--- --
----- ----
----
---
---------------- -- -- -
---------------- ------ -- ------- -- ---- -------
---2. 使用 api2swagger-ext
在项目的根目录下创建一个 swagger.json 文件并将以下内容添加进去：
{
"swagger": "2.0",
"info": {
"title": "API 接口文档",
"version": "1.0.0"
},
"paths": {}
}然后在项目的根目录下创建一个 convert.js 文件，添加以下代码：
-- -------------------- ---- -------
----- ----------- - ---------------------------
----- -- - --------------
----- ------- - -----------------
----- ------- - -
----- ------------------------
----- -
-------- --------
------ ---- ------
------------ ---- -------
-
--
------------------------------ -------- --------
--------------- -- -
---------------------------------- ----------------------- ----- ----
-------------------- ---- ---- --- ---- ------- ----------------
-------------- -- -
-----------------
---然后在命令行中执行以下命令：
node convert.js
当执行完成后，会在项目的根目录下生成 swagger.json 文件，包含了 API 接口的 Swagger 规范。
3. 查看 Swagger 文档
我们可以用 Swagger UI 来查看这个 Swagger 规范。
首先，安装 Swagger UI：
npm install swagger-ui-express --save
然后，在 convert.js 文件中添加以下代码：
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));然后，在浏览器中访问 http://localhost:8080/api-docs，就可以看到 Swagger 页面了。
总结
api2swagger-ext 是一个非常方便和实用的工具，它可以将本地项目的 API 接口转换成 Swagger 规范，并且支持多种语言和框架。使用 api2swagger-ext 能够大大提高 API 接口的规范化程度和文档编写的效率，从而提高团队的协作效率，值得开发者们去尝试。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055cb681e8991b448da384