简介
express-swag 是一个能够自动生成 Swagger API 文档的中间件，它依赖于 express 框架。使用 express-swag 能够很方便的将 express 应用程序的路由文档化为 Swagger API 文档。本篇文章将详细介绍 express-swag 的安装和使用方法。
安装
你可以通过 NPM 进行安装 express-swag。在命令行中输入以下命令：
$ npm install express-swag
安装成功后，就能够在项目中使用 express-swag。
使用说明
需要注意的是，在使用 express-swag 之前，你需要将你的 API 路由先添加到 express 应用程序中。接着，你需要在路由文件中引入 express-swag 包，以及引入 swaggerUi，后者是一个用于渲染 Swagger API 文档的工具，需要是 swagger-ui-express 包。
要添加 express-swag，只需要在 express 实例中使用 app.use()。
-- -------------------- ---- -------
----- ------- - -------------------
----- ------ - -----------------
----- -------------- - ------------------------
----- --------- - ------------------------------
----- ------- - -
----------- -
-------- --------
----- -
------ --- ---- -----
-------- --------
--
--
-- ---- -- ----- -- -- ---------- --- --- ---- --- ----- ---------------
----- ------------------- --------------------
--
------------------------
--------------- ------------- ---- -
-----------------
---
-------------------- ------------- ---- -
------------------
---
--------------------- ------------- ---- -
--------------- -------
---
-------------------- -----------------
-------------------- --------------------- - ----------- ---------- ----
------------ --------你需要在 options 对象中设置以下属性：
- openapi：必选，Swagger 版本号，目前只支持版本号为 3.0.0 及以上的 Swagger 格式。
- info：必选，包含标题和版本号的信息对象。
- apis：必选，由你提供的要在 Swagger API 文档中呈现的文件的数组。
接着访问 http://localhost:3000/api-docs 会渲染控制台上的 Swagger UI。你可以选择通过 swaggerUrl 属性提供 JSON URL，从而在运行时使用 Swagger UI 显示 API 文档。
app.get('/swagger', function(req, res) {
res.json(options);
});这时你就可以通过 URL：http://localhost:3000/api-docs 查看 Swagger UI。
API 文件结构
我们假设有一个名为 users.js 的路由文件，例如：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ------ - ----------------- --- - -------- - ----------- - ---- - -------- ------ - ------------ ------ - ---------- - ---- - ------------ -- -- -------------------- ------------- ---- - ------------------ --- -------------- - -------
通过在文件的顶部使用 @swagger 标识符，你可以指定此文件中的 API 的 Swagger 实现。现在，当你访问 http://localhost:3000/api-docs，即显示了在 users.js 文件中定义的 API。属性 summary 描述了 API 的简要概述，并在 Swagger UI 的 API 列表中显示，在你点击 API 时弹出对话框，显示详细的 API 描述。
总结
在本文中，我们介绍了 express-swag 包的使用方法，希望能够帮助你更方便地创建和维护 API 文档。本文提供的示例代码可供参考，切实降低您的学习难度，如有疑问，欢迎留言。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055aa481e8991b448d81d9