使用OpenAPI和Swagger UI编写的REST API文档 | 作者：Joshua Ondieki

记录REST OpenAPI 和 Swagger UI 为 Express REST API 编写文档。

什么是 OpenAPI 和 Swagger UI？

在开始之前，我们需要了解一些关键术语。

YAML

YAML 是一种人类可读的标记语言，常用于配置文件。它的语法简单且直观，非常适合用来描述 API 的结构和行为。

Swagger UI

Swagger UI 是一个开源工具，可以将 OpenAPI 规范的文档转换为直观的用户界面。通过 Swagger UI，开发者可以交互式地测试 API，而无需编写额外的客户端代码。

使用 Swagger UI 记录 API 的两种方法

使用 Swagger UI 记录 API 通常有两种方式：

在代码的每个端点上添加注释

Swagger UI 会解析这些注释并生成一个直观的用户界面。
使用独立的 YAML 文件记录端点

将所有 API 文档保存在与代码分离的 YAML 文件中。这种方法更适合大型项目，也是本文的重点。

设置服务器以提供 Swagger UI 服务

在开始记录 API 之前，我们需要设置服务器，使其能够通过指定的路由（如 /docs）提供 Swagger UI 服务。

所需依赖

我们需要安装以下两个 Node.js 包：

swagger-ui-express：用于生成美观的用户界面。
yamljs：用于将 YAML 文件加载为 JavaScript 对象。

安装命令如下：

npm install swagger-ui-express yamljs

配置 OpenAPI 文档

以下是一个简单的 OpenAPI 文档示例，使用 YAML 格式描述：

openapi: 3.0.0
info:
  title: Express API With OpenAPI Docs
  description: A simple express REST API with OpenAPI docs generated by Swagger UI.
  version: 1.0.0
servers:
  - url: /

将上述内容保存为 api.yaml 文件，并在 Express 应用中加载它。

添加路径和组件

在 YAML 文件中，我们需要定义 API 的路径（paths），即端点的具体描述。这些路径将记录 API 的行为，例如请求方法、参数和响应格式。

为了避免重复，我们可以使用可重用的组件（components）。例如，定义常用的响应结构或参数模板，并在多个路径中引用它们。

总结

通过本文的介绍，我们学习了如何使用 OpenAPI 和 Swagger UI 为 Express REST API 编写文档。使用 YAML 文件记录 API 不仅使文档更清晰，还能与代码分离，便于维护和扩展。希望本文能够帮助您更高效地记录和管理 API 文档。

原文链接: https://medium.com/@joshuaondieki/rest-api-docs-with-openapi-swagger-ui-de9cd7944c6