Swagger 是一个流行的 API 开发工具，它可以让开发者更好地设计和文档化 RESTful APIs。SwaggerUI 是 Swagger 最受欢迎的插件之一，它可以展示以 Swagger 规范编写的 RESTful API 文档。本文将介绍如何使用 SwaggerUI 展示 RESTful API 文档，并提供示例代码。
安装 SwaggerUI
首先，我们需要从官网下载最新版本的 SwaggerUI。下载地址为：https://github.com/swagger-api/swagger-ui/releases。下载完成后，我们需要将下载的文件解压到我们的项目目录下。
假设我们将 SwaggerUI 放在项目的根目录下，通过浏览器访问 http://localhost:8080/swagger-ui/，我们可以看到 SwaggerUI 的默认界面。
创建 Swagger 规范
Swagger 规范是一种以 YAML 或 JSON 格式编写的文档，其中包含了 API 的详细信息，如 API 的路径、HTTP 方法、参数、响应等。我们可以使用 Swagger 规范来定义 RESTful APIs 并生成文档。
以下是一个简单的示例：
-- -------------------- ---- -------
-------- -----
-----
------ ----- ----
-------- -------
----- -----------------
--------- -----
--------
- -------
------
------
----
-------- ---- --- -----
----------
------
------------ -- ---- -- -----
-------
----- -------
------
----- -------------------
------------
----
----- --------
-----------
-----
----- --------
----
----- --------这个规范定义了一个 Pets API，API 的根路径为 /v1/pets，并使用 HTTPS 协议。该 API 有一个 GET 方法，用于获取所有宠物的列表。响应是一个包含宠物信息的数组。宠物的定义在 definitions 部分。
展示 Swagger 规范
我们需要将 Swagger 规范转换为 JSON 格式，然后将其嵌入到我们的 HTML 页面中。以下是一个简单的示例：
-- -------------------- ---- -------
--------- -----
----- ----------
------
----- ----------------
-------------- ----------
----- ---------------- --------------- ----------------------------------------
------- ------------------------------------------------------
------- -----------------------------------------------------------------
-------
------
---- ----------------------
--------
------------- - ---------- -
-- -- ------- --
-----------------------
--------- -- -----------
---------- -- -
-- - --------- ------
----- -- - -----------------
----- -----
------- --------------
-------- -
-----------------------------
-------------------------
--
------- ------------
---
---
-
---------
-------
-------该 HTML 页面使用了 SwaggerUI 的两个库：swagger-ui-bundle.js 和 swagger-ui-standalone-preset.js。首先加载了这两个库，然后将“Swagger UI”渲染到页面上。窗口加载完毕后，我们使用 fetch() 方法从服务器获取 Swagger 规范，并将其传递给 SwaggerUIBundle() 方法进行渲染。
以上代码假定我们的 Swagger 规范保存在服务器的根目录下，并且文件名为 api-spec.json。
我们可以通过访问该 HTML 页面来查看我们的 API 文档。
结论
使用 SwaggerUI 可以轻松地展示 RESTful API 文档，并且使得编写 API 文档变得容易而不失优雅。希望这篇文章能够帮助读者更好地了解 Swagger 和 SwaggerUI，并加速前端开发工作。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6736b5f20bc820c58255ee51