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

一. OpenAPI 的核心概念

OpenAPI 是一种标准，用于描述人类和机器都可以理解的 HTTP API 文档。遵循 OpenAPI 规范构建 API，可以减少开发者与消费者之间的沟通成本，明确 API 的行为规范。

OpenAPI 描述文档通常被称为 API 契约（API Contract），它像契约一样规定了开发者必须实现的功能，以及消费者需要遵守的规则。API 契约的优势包括：

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

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

二. 使用 OpenAPI 与 Express.js 构建 API

本节将逐步介绍如何使用 Express.js 构建符合 OpenAPI 规范的 API，并配置 API 文档。

1. 先决条件

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

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

2. 创建 Express 应用

a. 初始化项目

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

b. 安装依赖

npm install express

c. 创建入口文件

在项目根目录创建 index.js：

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 会显示错误，因为尚未配置路由。

3. 将 OpenAPI 与 Express.js 集成

为了实现符合 OpenAPI 的 API，我们使用 express-openapi 包。

a. 安装 express-openapi

npm install express-openapi

b. 配置 OpenAPI 定义

创建 doc/api-definition-base.yml：

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

c. 初始化 OpenAPI

修改 index.js：

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

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

d. 定义路由

创建 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 文档。

1. 配置 Bump.sh

a. 安装 Bump CLI

npm install -g @bump-sh/cli

b. 生成 API 定义文件

创建 contract.js：

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

c. 部署文档

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

d. 自动化部署

配置 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 契约：

提升 API 的质量和可维护性。
帮助开发者和消费者快速理解和使用 API。
利用 Bump.sh 提供的变更日志和通知工具，实现高效协作。

将 API 文档集成到开发流程中，可以显著优化团队的开发效率和文档管理水平。

原文链接

Express API with OpenAPI | Bump.sh