搭配OpenAPI Backend使用MSW做接口模拟时出现Unknown operation错误

问题原因 #

1. OpenAPIBackend未初始化：创建实例后没有调用init()方法，OpenAPI定义的路径、Schema等内容没有被解析加载，无法匹配/links对应的接口操作，直接抛出Unknown operation错误。
2. OpenAPI定义缺失operationId：你的api.json中所有接口都没有配置operationId字段，而代码中mockResponseForOperation方法依赖该字段查找对应接口的Mock配置，即使路径匹配成功也无法生成响应。
3. 响应格式不兼容：你注册的handler使用了Express风格的参数结构，和MSW的响应构造逻辑不匹配，无法正确返回符合MSW要求的响应格式。

解决方案 #

步骤1：补充OpenAPI定义的operationId字段 #

修改api.json，给每个路径下的接口新增operationId配置：

{
  "paths": {
    "/config": {
      "get": {
        "operationId": "getConfig",
        // 其余原有内容保持不变
      }
    },
    "/links": {
      "get": {
        "operationId": "getLinks",
        // 其余原有内容保持不变
      }
    },
    "/kpis": {
      "get": {
        "operationId": "getKpis",
        // 其余原有内容保持不变
      }
    }
  }
}

步骤2：重写mock/browser.ts逻辑，适配初始化和响应格式 #

import { setupWorker, rest } from 'msw';
import { OpenAPIBackend } from 'openapi-backend';
import type { Document } from 'openapi-backend';
import definition from './api.json';

const api = new OpenAPIBackend({ definition: definition as Document });

// 注册适配MSW格式的响应handler
api.register('notFound', () => {
  return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404 });
});
api.registerHandler('notImplemented', async (c) => {
  const { status, mock } = await api.mockResponseForOperation(
    c.operation.operationId as string
  );
  return new Response(JSON.stringify(mock), { status });
});
api.register('validationFail', (c) => {
  return new Response(JSON.stringify({ error: c.validation.errors }), { status: 400 });
});

// 初始化OpenAPIBackend，避免重复初始化
let isApiInited = false;
const initOpenApi = async () => {
  if (!isApiInited) {
    await api.init();
    isApiInited = true;
  }
};

const worker = setupWorker(
  // 匹配所有请求方法
  rest.all('/*', async (req) => {
    await initOpenApi();
    // 构造OpenAPIBackend需要的请求参数
    const reqParams = {
      path: req.url.pathname,
      method: req.method,
      headers: req.headers.all(),
      query: Object.fromEntries(req.url.searchParams.entries()),
      body: await req.json().catch(() => undefined),
    };
    return api.handleRequest(reqParams);
  })
);

export default worker;

步骤3：调整启动配置（可选，更稳定） #

修改index.tsx的worker启动配置，避免未处理的请求报错：

import worker from './mocks/browser';

if (process.env.NODE_ENV === 'development') {
  worker.start({
    onUnhandledRequest: 'bypass',
  });
}

内容的提问来源于stack exchange，提问作者Bojan Golubovic