mocking-apis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mocking APIs

API模拟

Overview

概述

Generate mock API servers from OpenAPI specifications that return realistic, schema-compliant response data for development and testing. Support dynamic response generation with Faker.js data, configurable latency simulation, stateful CRUD behavior, and request recording for contract testing validation.

基于OpenAPI规范生成Mock API服务器，返回符合Schema的真实响应数据，用于开发与测试场景。支持通过Faker.js生成动态响应数据、可配置的延迟模拟、有状态的CRUD行为，以及用于契约测试验证的请求录制功能。

Prerequisites

前提条件

OpenAPI 3.0+ specification file with response schema definitions
Mock server runtime: Prism (Stoplight), json-server, MSW (Mock Service Worker), or WireMock
Faker.js or equivalent for realistic test data generation
Docker for containerized mock server deployment (optional but recommended)
Frontend or consumer application needing API stubs for parallel development

OpenAPI 3.0+规范文件，包含响应Schema定义
Mock服务器运行时：Prism (Stoplight)、json-server、MSW (Mock Service Worker) 或 WireMock
Faker.js或同类工具，用于生成真实测试数据
Docker（可选但推荐），用于容器化部署Mock服务器
需要API桩的前端或消费端应用，以支持并行开发

Instructions

操作步骤

Read the OpenAPI specification using Read and extract all endpoint definitions, response schemas, and example values to build the mock response inventory.
Generate response fixtures for each endpoint using schema-aware data generation: realistic names (Faker), valid emails, properly formatted dates, and relational IDs that reference other mock entities.
Configure the mock server to match requests by method, path pattern, query parameters, and request body content type, returning the appropriate fixture.
Add stateful behavior for CRUD operations: POST creates a record in memory, GET returns it, PUT updates it, DELETE removes it -- enabling realistic integration testing flows.
Implement configurable response delays (50-500ms per endpoint) to simulate real-world latency and test client timeout handling.
Add error scenario mocking: configure specific request patterns to return 400, 401, 404, 429, or 500 responses for testing error handling paths.
Enable request recording that captures all incoming requests with timestamps and headers for later replay in contract tests.
Create a startup script that launches the mock server on a configurable port with hot-reload when fixture files change.

See

${CLAUDE_SKILL_DIR}/references/implementation.md

for the full implementation guide.

读取OpenAPI规范，提取所有端点定义、响应Schema和示例值，构建Mock响应库。
为每个端点生成响应fixtures：使用Schema感知的数据生成方式，生成真实姓名（Faker）、有效邮箱、格式正确的日期，以及关联其他Mock实体的关系ID。
配置Mock服务器，根据请求方法、路径模式、查询参数和请求正文内容类型匹配请求，并返回对应的fixture。
为CRUD操作添加有状态行为：POST请求在内存中创建记录，GET请求返回该记录，PUT请求更新记录，DELETE请求删除记录——实现真实的集成测试流程。
实现可配置的响应延迟（每个端点50-500ms），模拟真实世界的网络延迟，测试客户端超时处理逻辑。
添加错误场景模拟：配置特定请求模式，返回400、401、404、429或500响应，用于测试错误处理路径。
启用请求录制功能，捕获所有传入请求的时间戳和请求头，以便后续在契约测试中重放。
创建启动脚本，在可配置端口启动Mock服务器，当fixture文件变更时支持热重载。

更多实现细节请参考

${CLAUDE_SKILL_DIR}/references/implementation.md

。

Output

输出结果

```
${CLAUDE_SKILL_DIR}/mocks/server.js
```
- Mock server entry point with route registration
```
${CLAUDE_SKILL_DIR}/mocks/fixtures/
```
- Per-endpoint response fixture JSON files
```
${CLAUDE_SKILL_DIR}/mocks/generators/
```
- Dynamic response generators using Faker.js
```
${CLAUDE_SKILL_DIR}/mocks/scenarios/
```
- Error scenario configurations (4xx, 5xx responses)
```
${CLAUDE_SKILL_DIR}/mocks/state.js
```
- In-memory state store for CRUD behavior
```
${CLAUDE_SKILL_DIR}/mocks/recordings/
```
- Captured request logs for contract testing

${CLAUDE_SKILL_DIR}/docker-compose.mock.yml

- Docker configuration for mock server

```
${CLAUDE_SKILL_DIR}/mocks/server.js
```
- Mock服务器入口文件，包含路由注册
```
${CLAUDE_SKILL_DIR}/mocks/fixtures/
```
- 每个端点对应的响应fixture JSON文件
```
${CLAUDE_SKILL_DIR}/mocks/generators/
```
- 使用Faker.js的动态响应生成器
```
${CLAUDE_SKILL_DIR}/mocks/scenarios/
```
- 错误场景配置（4xx、5xx响应）
```
${CLAUDE_SKILL_DIR}/mocks/state.js
```
- 用于CRUD行为的内存状态存储
```
${CLAUDE_SKILL_DIR}/mocks/recordings/
```
- 捕获的请求日志，用于契约测试

${CLAUDE_SKILL_DIR}/docker-compose.mock.yml

- Mock服务器的Docker配置

Error Handling

错误处理

Error	Cause	Solution
Schema mismatch	Mock response does not match updated OpenAPI spec	Run spec-to-fixture sync on spec change; add CI check comparing fixture schemas
Missing endpoint	Consumer requests path not defined in OpenAPI spec	Return 501 with message listing available endpoints; log unknown path for spec update
Stale fixtures	Mock data becomes unrealistic after API schema evolution	Regenerate fixtures from latest spec; use generators over static fixtures for evolving APIs
Port conflict	Mock server port already in use by another dev service	Make port configurable via environment variable; default to spec-defined server URL port
State leak between tests	Stateful mock retains data from previous test run	Reset in-memory state before each test suite; expose `POST /mock/reset` admin endpoint

Refer to

${CLAUDE_SKILL_DIR}/references/errors.md

for comprehensive error patterns.

错误类型	原因	解决方案
Schema不匹配	Mock响应与更新后的OpenAPI规范不一致	当规范变更时，运行规范到fixture的同步操作；添加CI检查，对比fixture与Schema是否一致
端点缺失	消费端请求的路径未在OpenAPI规范中定义	返回501响应，附带可用端点列表；记录未知路径，用于更新规范
Fixture过时	API Schema演进后，Mock数据不再真实	根据最新规范重新生成fixture；对于不断演进的API，使用生成器而非静态fixture
端口冲突	Mock服务器端口已被其他开发服务占用	通过环境变量配置端口；默认使用规范中定义的服务器URL端口
测试间状态泄漏	有状态Mock保留了上一次测试运行的数据	在每个测试套件运行前重置内存状态；暴露 `POST /mock/reset` 管理端点

更多错误模式请参考

${CLAUDE_SKILL_DIR}/references/errors.md

。

Examples

示例

Frontend parallel development: Launch a Prism mock server from the OpenAPI spec so frontend developers can build against realistic API responses while backend implementation is in progress.

Integration test isolation: Use MSW (Mock Service Worker) to intercept HTTP requests in Node.js test suites, returning fixture responses without network calls, with per-test response customization.

Contract testing: Record all requests to the mock server during frontend E2E tests, then replay them against the real backend to verify the mock accurately represents actual API behavior.

See

${CLAUDE_SKILL_DIR}/references/examples.md

for additional examples.

前端并行开发：基于OpenAPI规范启动Prism Mock服务器，让前端开发者在后端实现完成前，即可基于真实的API响应进行开发。

集成测试隔离：使用MSW (Mock Service Worker) 在Node.js测试套件中拦截HTTP请求，返回fixture响应，无需网络调用，且支持按测试用例自定义响应。

契约测试：在前端E2E测试期间，录制所有发送到Mock服务器的请求，然后在真实后端上重放这些请求，验证Mock是否准确反映了实际API行为。

更多示例请参考

${CLAUDE_SKILL_DIR}/references/examples.md

。

Resources

资源

Prism (Stoplight): https://stoplight.io/open-source/prism
Mock Service Worker (MSW): https://mswjs.io/
WireMock: https://wiremock.org/
Faker.js for realistic data generation: https://fakerjs.dev/

Prism (Stoplight): https://stoplight.io/open-source/prism
Mock Service Worker (MSW): https://mswjs.io/
WireMock: https://wiremock.org/
Faker.js（生成真实数据）: https://fakerjs.dev/