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 钉住返回值

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

写法	位置	什么时候用
`example: Odie`	schema 的单个字段	想让 mock 中该字段恒为固定值，如单测要对精确返回值断言
`examples.garfield.value`	整个响应	要模拟多套数据状态（有数据 / 无数据），按名字取不同返回

比如 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 生成符合规范的状态码与数据的库方法）自动产出响应。什么场景需要它：你还没写任何业务逻辑，想让规范里的接口全部可调用；或同一服务里真假接口混用——已就绪的注册处理器，其余走回调兜底。