引言
在前端开发过程中，RESTful API（简称“API”）是不可或缺的一环。而对于 API 的文档生成，我们往往会利用 Swagger-ui 工具来实现。Swagger-ui 是 Swagger 项目的官方工具，能够以交互式的方式展现 API 的文档。
本文将详细介绍如何运用 Swagger-ui 生成 RESTful API 文档，内容涵盖了从 Swagger 基本概念的介绍，到如何集成 Swagger-ui 到项目中，并构建实际的 API 文档。
Swagger 的基本概念
Swagger 是一个流行的、支持多语言的 RESTful API 开发框架。它的主要作用是提供 API 的自描述信息，使得 API 在无人交互的情况下也能通过电子设备得以使用。Swagger 定义了一个标准语言，通过该语言描述 API 的信息。
Swagger 的描述语言通常是 JSON 或 YAML 格式的文件，其中包含了 API 的基本信息，比如 API 的版本、文档、作者等等，还包含了 API 的路径、请求方式、参数和返回值等详细信息。后面我们将在示例中演示如何使用 YAML 来描述 API。
Swagger 的另一个重要组成部分是 Swagger-ui，它是 Swagger 专门为文档生成的浏览器插件。只要我们将 Swagger 描述的 API 文件加载到 Swagger-ui 中，Swagger-ui 就会根据文件内容自动生成文档。Swagger-ui 支持多种浏览器环境，包括 Chrome、Safari、Firefox 和 Edge。
集成 Swagger-ui
接下来，我们将介绍如何集成 Swagger-ui 到你的项目中。在本示例中，我们将使用 Node.js 进行演示。请确保在本地已经安装了 Node.js 环境。
- 下载 Swagger-ui
首先，我们需要将 Swagger-ui 下载到本地。你可以在 Github 上查找更新的版本号并下载：https://github.com/swagger-api/swagger-ui/releases。
下载完成之后，解压缩并配置相应的目录和文件。
- 构建 Swagger 文档
接下来，我们需要通过 Swagger 描述语言来构建 API 文档。这里我们使用 YAML 的方式来描述文档。以下是一个简单的 Swagger 文件示例：
// javascriptcn.com 代码示例
swagger: "2.0"
info:
title: "My API"
description: "API description"
version: "1.0.0"
basePath: "/api"
schemes:
- "http"
- "https"
paths:
/test:
get:
summary: "test GET API"
description: "test GET API"
responses:
200:
description: "OK"上述 YAML 描述了一个名为 My API 的 API，它的版本是 1.0.0，基本路径是 /api。该 API 只有一个接口 /test，该接口使用 GET 方式请求，其响应状态码为 200，该接口的主要作用是返回 OK。你可以根据项目需要将其进行修改或扩展。
- 将 Swagger 文档加载到 Swagger-ui 中
在运行 Swagger-ui 之前，我们需要将构建好的 Swagger 文档加载到 Swagger-ui 相应的目录中。默认情况下，Swagger-ui 的配置文件指向了./dist目录，所以我们需要将构建好的文件放到该目录中。如果你使用的是默认的 directory 目录结构，你只需要将构建好的文档拷贝到相应的目录：/directory/to/swagger-ui/dist/。
接下来，通过 web 浏览器访问 http://localhost:8080，你将能够看到 Swagger-ui 已经根据我们的文档，生成了漂亮的 API 文档。
总结
本文讲述了如何运用 Swagger-ui 生成 RESTful API 文档。我们通过介绍 Swagger 的基本概念，向读者普及了 Swagger 描述语言和 Swagger-ui 工具的基本知识。此外，通过实例演示，我们向读者详述了如何将Swagger-ui 集成到自己的项目中，进而构建生成实际的 API 文档。希望能给大家带来一些帮助。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/6540ae037d4982a6eba355e3