openapi-backend 5 分钟上手：用 OpenAPI 规范起 mock 服务，前端联调不用排队等接口

openapi-backend 5 分钟上手：用 OpenAPI 规范起 mock 服务，前端联调不用排队等接口

【免费下载链接】openapi-backendBuild, Validate, Route, Authenticate and Mock using OpenAPI项目地址: https://gitcode.com/gh_mirrors/op/openapi-backend

前端联调经常卡在等接口：后端没做完接口，前端只能停工或手写假数据。openapi-backend 可以直接把接口描述文档变成 mock 服务，前端在后端没实现之前就能调通接口。

▶️ 先看效果：curl 一条命令拿到 mock 数据

服务启动后监听 9000 端口：

curl -i http://localhost:9000/pets

返回：

[{ "id": 1, "name": "Odie" }]

没有任何后端代码，/pets 就返回结构符合规范的宠物数组。name 是 Odie 不是随机值，是规范里 example 字段钉住的，后文细讲。

🚀 三步跑起来：克隆、读规范、验证

克隆仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/op/openapi-backend cd openapi-backend/examples/express-ts-mock npm install

这里用仓库内的 Express + TypeScript 示例，postinstall 脚本会自动把 TS 编译一遍，Node 14+ 即可。

openapi.yml 最小写法：operationId 与 example

openapi.yml 是 OpenAPI 规范（用 YAML 或 JSON 书写的接口描述文档，定义每个接口的 URL、参数和响应结构）的落地文件。理解最小片段就够了：

paths: /pets: get: operationId: getPets responses: '200': $ref: '#/components/responses/ListPetsRes' components: responses: ListPetsRes: content: application/json: schema: type: array # 数组，每项含 id(integer, >=1) 和 name(string, example: Odie)

只需看懂两处：

• operationId：每个 API 操作的唯一标识（如 getPets），openapi-backend 靠它把请求路由到对应处理器，后面也用它来取 mock；
• 响应 schema：'200'通过$ref引用ListPetsRes，schema 声明了一个数组，每项有 id/name，其中 name 上的example: Odie会被 mock 生成器直接采用。

启动服务并验证 /pets

npm run dev

控制台打印api listening at http://localhost:9000后即可验证：

curl -i http://localhost:9000/pets curl -i http://localhost:9000/pets/1a

第一条返回 200 和上面的 mock 数据；第二条的 id 不是整数，被校验拦截，validationFail 处理器返回 400 和错误明细。也就是说 mock 服务的校验能力是真的，不只是假数据。

图片占位：此处可插入终端执行上述两条 curl 命令及返回结果的截图（建议 4:3 横版）。

🎛️ 怎么定制 mock 数据：example、examples 与 notImplemented 回调

用 example / examples 钉住返回值

规范里有两种"钉法"，适用场景不同：

比如 openapi.yml 中 PetRes 声明了examples.garfield.value为{ id: 1, name: 'Garfield' }，GET /pets/1 就固定返回这个对象。

让 notImplemented 处理未实现的接口

关键配置在 index.ts：

const api = new OpenAPIBackend({ definition: path.join(__dirname, '..', 'openapi.yml'), handlers: { validationFail: async (c, req, res) => res.status(400).json({ err: c.validation.errors }), notFound: async (c, req, res) => res.status(404).json({ err: 'not found' }), notImplemented: async (c, req, res) => { const { status, mock } = c.api.mockResponseForOperation(c.operation.operationId); return res.status(status).json(mock); }, }, });

notImplemented回调在请求命中一个没有注册真实处理器的接口时触发，示例里用mockResponseForOperation（按接口的 operationId 生成符合规范的状态码与数据的库方法）自动产出响应。什么场景需要它：你还没写任何业务逻辑，想让规范里的接口全部可调用；或同一服务里真假接口混用——已就绪的注册处理器，其余走回调兜底。

🔌 接入真实项目：baseURL 切换与测试

baseURL 怎么切换：一行配置的事

前端代码只需把请求基地址指向 http://localhost:9000（如 axios 的baseURL），后端就绪后换成真实网关域名，改的是配置而不是业务代码。想保证 mock 数据与最终 API 一致，最好前后端共用同一份 OpenAPI 文档，本仓库的示例正是这么配的。

用测试锁定 mock 行为

index.test.ts 的做法值得照抄：beforeAll 里拉起服务、等 9000 端口就绪，再发真实 HTTP 请求，断言三件事：

• GET /pets返回 200，且是包含{ id: 1, name: 'Odie' }的数组；
• GET /pets/1a返回 400，且带错误信息；
• GET /unknown返回 404。

三条断言就能确认 mock 服务的行为符合规范。

完整可运行示例在 examples/express-ts-mock/。下一步可以把示例 openapi.yml 换成你自己项目的 OpenAPI 文档，mock 服务就会跟着真实接口走；如果不用 Express，examples/ 目录还有 Koa、Fastify、Hapi 等实现可参考移植。

【免费下载链接】openapi-backendBuild, Validate, Route, Authenticate and Mock using OpenAPI项目地址: https://gitcode.com/gh_mirrors/op/openapi-backend