Swagger 是一种描述 RESTful 服务的工具，并且可以生成交互式文档。Swagger UI 是 Swagger 的一个前端界面，并且可以直接嵌入我们的网页中，以方便用户查看和调用我们的接口。swagger-ui-express 是 Express 框架的一个中间件，可以让我们在 Express 中使用 Swagger UI。本文将介绍如何使用 npm 包 swagger-ui-express。
安装
使用 npm 安装 swagger-ui-express：
npm install swagger-ui-express
使用
首先在 Express 的路由中引入该中间件：
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));其中 swaggerDocument 是 Swagger 的文档对象，可以是一个本地 JSON 文件或者一个远程 URL。以下是一个本地 JSON 文件的示例：
const swaggerDocument = require('./swagger.json');Swagger 文档格式
Swagger 文档是一个 JSON 对象，包含了接口的各种信息，包括接口的 URL、请求方式、请求和响应的参数等。以下是一个简单的示例：
-- -------------------- ---- -------
-
---------- ------
------- -
---------- --------
-------- --------- -----
-------------- -- ------ --- ---- ---- - -------- -- -- ------- -- ----------- -------- -- --- ------- --- ---------------
---------- -
------- ------
------ -------------------------------------
-
--
------- ----------------------
----------- ----------
---------- -
-------
--
-------- -
---------------- -
------ -
---------- ----- --- -- ----
-------------- -------- - ------ -----
-------------- -------------
------------ -
------ -
-------------- ----------- -----------
--------- -
------- -------------------
-
--
------ -
-------------- -------- --- ---
--
------ -
-------------- ---- --- ------
-
-
-
-
--
-------------- -
------ -
------- ---------
------------- -
----- -
------- ----------
--------- -------
--
------- -
------- --------
--
------------ -
------- --------
-------- -
------- --------
-
--
--------- -
------- ---------
-------------- ---- ------ -- --- ------
-
--
------ -
------- -----
-
-
-
-其中：
swagger表示使用的 Swagger 版本号；info包含了接口的基本信息；host和basePath表示接口的域名和地址；schemes表示使用的协议；paths包含了所有的接口信息；definitions包含了所有的参数和响应数据格式。
可以查看 Swagger 官网文档了解更多信息。
自定义样式
Swagger UI 默认有自己的样式，但是我们可以针对自己的项目进行自定义。
首先安装样式文件：
npm install swagger-ui-dist
在 app.js 中引入：
-- -------------------- ---- -------
----- ------- - -------------------
----- --------- - ------------------------------
----- ---- - ----------------
----- ---- - ------------------
----- --------------- - ------------------------------ -----------------
----- --- - ----------
-------------------- ---------------- -------------------------------- -
---------- ---------------- --- - ------------------------- ---
---------------- --- --- -----
-------------- --------------
----
---------------- -- -- -
---------------- -- --------- -- ---- --------
---其中 customCss 可以自定义样式，customSiteTitle 可以自定义标题，customfavIcon 可以自定义网站图标。
总结
本文介绍了使用 swagger-ui-express 中间件在 Express 中使用 Swagger UI 的方法，并对 Swagger 文档格式进行了简单的介绍，以及如何自定义样式。希望对大家学习前端开发有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/197413