使用 OpenAPI 与 Express.js 构建高效 API 并通过 Bump.sh 管理文档

构建 API，可以有效减少开发者和消费者之间的摩擦，尤其是在 API 应该如何运行的方面。本文将通过一个完整的教程，介绍如何使用 OpenAPI 和 Express.js 创建 API，并利用 Bump.sh 记录和管理 API 文档。

OpenAPI 的核心概念

HTTP API 的标准化语言，它允许人类和机器无需访问源代码即可理解和交互 API。有效的 OpenAPI 描述文档通常被称为 API 契约（API Contract），因为它像契约一样，规定了开发者必须实现的行为以及消费者需要遵守的规则。

API 契约的优势包括：

减轻开发者的负担。
提高首次使用者的易用性。
借助自动化工具减少生成客户端代码、文档以及验证输入/输出数据的工作量。

接下来，我们将通过构建一个 Express 应用程序，展示如何利用 OpenAPI 契约，并使用 Bump.sh 生成和管理文档。

使用 OpenAPI 和 Express.js 构建 API

在本节中，我们将逐步介绍如何使用 Express.js 构建一个遵循 OpenAPI 规范的 API，同时配置 API 文档。

先决条件

在开始之前，您需要具备以下条件：

熟悉 JavaScript 和 Node.js。
已安装 Node.js 环境。
使用 Node.js 包管理器（如 npm）。
拥有一个 Bump.sh 账户。

创建 Express 应用程序

初始化项目

创建一个新文件夹并初始化项目：

   mkdir express-oas
   cd express-oas
   npm init -y

安装依赖

安装 Express 依赖：

   npm install express

创建入口文件

在项目根目录创建 index.js 文件，并初始化 Express 应用程序：

   const express = require('express');
   const app = express();

   app.use(express.json());   app.listen(3000, () => {
       console.log('Server is running on http://localhost:3000');
   });

运行应用程序：

   node index.js

此时，访问 http://localhost:3000 会显示错误，因为尚未配置路由。

将 OpenAPI 与 Express.js 集成

为了实现符合 OpenAPI 规范的 API，我们将使用 express-openapi 包。以下是具体步骤：

安装 express-openapi

   npm install express-openapi

配置 OpenAPI 定义

在项目中创建一个 doc/api-definition-base.yml 文件，用于定义 API 的基本结构：

   openapi: 3.1.0
   info:
     title: Sample API
     version: 1.0.0
   paths: {}

初始化 OpenAPI

修改 index.js 文件，添加以下代码：

   const { initialize } = require('express-openapi');

   initialize({
       app,
       apiDoc: './doc/api-definition-base.yml',
       paths: './paths',
   });

定义路由

创建 paths 文件夹，并在其中添加路由文件。例如：

paths/users.js：

module.exports = {
 get(req, res) {
     res.json({ message: 'Get all users' });
 },
};

paths/users/{id}.js：

module.exports = {
 get(req, res) {
     res.json({ message: Get user with ID: ${req.params.id} });
 },
};

运行应用程序

重新启动应用程序后，访问 http://localhost:3000/api-definition 可以查看生成的 API 定义。

使用 Bump.sh 记录 API 文档

Bump.sh 是一个强大的工具，可以帮助开发者根据 OpenAPI 契约生成和管理 API 文档。

配置 Bump.sh

安装 Bump CLI

在项目中安装 Bump CLI：

   npm install -g @bump-sh/cli

生成 API 定义文件

创建一个脚本 contract.js，用于生成 API 定义文件：

   const { initialize } = require('express-openapi');
   const fs = require('fs');

   initialize({
       app: null,
       apiDoc: './doc/api-definition-base.yml',
       paths: './paths',
   });   fs.writeFileSync('./doc/api-definition.json', JSON.stringify(apiDoc, null, 2));

运行脚本生成定义文件：

   node contract.js

部署文档

使用以下命令将文档部署到 Bump.sh：

   bump deploy ./doc/api-definition.json --token YOUR_TOKEN

自动化部署

配置 GitHub Actions，在每次代码推送时自动部署文档。创建 .github/workflows/bump-deploy.yml 文件：

   name: Deploy API Documentation

   on:
     push:
       branches:
         - main   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout code
           uses: actions/checkout@v2         - name: Install dependencies
           run: npm install         - name: Generate API definition
           run: node contract.js         - name: Deploy to Bump.sh
           run: bump deploy ./doc/api-definition.json --token ${{ secrets.BUMP_TOKEN }}

总结

通过本教程，您学习了如何使用 OpenAPI 和 Express.js 构建 API，并通过 Bump.sh 记录和管理 API 文档。正确记录 API 不仅能提升其质量和可维护性，还能帮助消费者快速理解和使用您的产品。

Bump.sh 提供了强大的功能，例如 API 变更日志和通知工具，使得开发者和消费者之间的协作更加高效。如果您希望进一步优化 API 文档管理，不妨尝试将其集成到您的开发流程中。

原文链接: https://bump.sh/blog/express-api-openapi