README.md
Rama main · réplica de lectura del repositorio original.
# spec0 Mock Server
Self-hosted OpenAPI mock server. Register a spec, get instant mock responses, manage variants and logs through a bundled web UI — no account required.
[](https://github.com/spec-0/mock-server/actions/workflows/ci.yml)
[](https://github.com/spec-0/mock-server/pkgs/container/mock-server)
[](LICENSE)
---
## Quick start
```bash
docker run -d -p 8080:8080 -v spec0-mock-data:/data ghcr.io/spec-0/mock-server
# open http://localhost:8080/ui/
```
Or with Docker Compose (data persists across restarts):
```bash
docker compose up -d
# http://localhost:8080/ui/
```
---
## UI walkthrough
```
+-----------+ +----------------+
| OpenAPI | | Runtime mock |
| document | ----> | /mock/{id}/… |
+-----------+ +----------------+
^
| manage in browser
+-----------------+
| Web UI /ui/ |
+-----------------+
```
After the server is up, open **`/ui/index.html`** to register specs, create mock servers, edit variants, and inspect logs.
---
## Features
- **[Auto-generated responses](docs/variants-and-strategies.md#generated-default-responses)** from your OpenAPI spec — uses your spec's `example` values first, then `default` / `enum`, then realistic made-up data
- **[Variant management](docs/variants-and-strategies.md)** — define multiple named responses per operation with `RANDOM`, `SEQUENTIAL`, `ROUND_ROBIN`, or `DEFAULT_ONLY` strategies
- **[Schema validation](docs/schema-validation.md)** (`OFF` / `WARN` / `STRICT`) — validate variant bodies against the OpenAPI response schema before saving, and validate incoming request bodies plus required query/path/header parameters at request time
- **[CEL expressions](docs/cel-expressions.md)** — dynamic responses evaluated at request time using request path params, query params, headers, and body
- **[Request logging](docs/request-logs.md)** — inspect full request/response pairs per mock server with infinite-scroll log viewer
- **[MCP integration](docs/mcp-integration.md)** — manage mock servers from Claude, Cursor, or any MCP-compatible AI assistant
- **[Drop-in base URL](docs/using-the-mock-url.md)** — point your app at `/mock/{serverId}` and all requests are intercepted; copy curl commands directly from the UI
- **Web UI** — bundled at `/ui/`, no separate frontend deployment
→ **[Full documentation](docs/README.md)**
---
## Schema validation modes
Set per mock server via `PATCH /mock-server/servers/{id}/config`:
| Mode | Behavior |
|------|----------|
| `OFF` (default) | No validation. Any response body is accepted. |
| `WARN` | Variant bodies are saved with violations logged/returned in `validationWarnings`; incoming request violations (bad body, missing required params) are logged only. |
| `STRICT` | Variant bodies are rejected with `400` if they violate the response schema; incoming requests are rejected with `400 request_validation_failed` if the body is invalid or a required query/path/header parameter is missing. |
Example — enable STRICT:
```bash
curl -X PATCH http://localhost:8080/mock-server/servers/{id}/config \
-H 'Content-Type: application/json' \
-d '{"schemaValidationMode":"STRICT"}'
```
---
## Configuration
Override any Spring Boot property via environment variables (relaxed binding):
| Env var | Default | Purpose |
|---------|---------|---------|
| `SPRING_DATASOURCE_URL` | `jdbc:h2:file:/data/spec0-mock;DB_CLOSE_ON_EXIT=FALSE` | Database location |
| `SERVER_PORT` | `8080` | HTTP port |
| `JAVA_OPTS` | _(empty)_ | Extra JVM flags (e.g. `-Xmx512m`) |
Example — custom port:
```bash
docker run -d -p 9090:9090 -e SERVER_PORT=9090 -v spec0-mock-data:/data spec0/mock-server
# http://localhost:9090/ui/
```
---
## Local development
Prerequisites: Java 17+, Maven 3.9+, Node 18+
Run two terminals from the repo root:
```bash
# Terminal 1 — backend on http://localhost:8080
make dev-backend
# Terminal 2 — UI on http://localhost:3000
make dev-ui # first time: cd ui && npm ci
```
Build the fat JAR (API + UI bundled):
```bash
cd ui && npm ci && npm run build && cd ..
mvn -pl standalone -am package -DskipTests
java -jar standalone/target/mock-server-standalone-*-exec.jar
```
> **Versions.** The pom says `1.0-SNAPSHOT` on every branch *and every tag* — release versions are
> applied by CI at publish time, not committed. So a build from a release tag produces
> `1.0-SNAPSHOT` artifacts unless you set the version yourself:
>
> ```bash
> mvn versions:set -DnewVersion=1.2.0 -DgenerateBackupPoms=false -DprocessAllModules=true
> ```
>
> This matters if you want a local `mvn install` to satisfy a dependency on a published version —
> without it the coordinates won't match and resolution falls back to the registry.
Run all tests:
```bash
./mvnw verify -Dskip.ui.copy=true
```
### Docker REST E2E
End-to-end tests hit a **real** HTTP server (not `@SpringBootTest` in-process). The script builds the fat JAR, builds the image, runs a container, waits for `/actuator/health`, runs `mock-server-e2e-tests` against that base URL, then removes the container.
```bash
chmod +x scripts/e2e-against-docker.sh # once
./scripts/e2e-against-docker.sh
```
Optional: `MOCK_SERVER_E2E_PORT=19090 ./scripts/e2e-against-docker.sh`, or `SKIP_UI_BUILD=1` if `ui/out` is already present.
To run the E2E test module manually against any running instance:
```bash
./mvnw -f e2e-tests/pom.xml test -Dmock.server.baseUrl=http://localhost:8080
```
---
## API reference
The full REST contract is available at `http://localhost:8080/swagger-ui.html` on a running instance, or statically at [`openapi.yaml`](openapi.yaml).
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and feature requests welcome via [GitHub Issues](https://github.com/spec0/mock-server/issues).
---
## License
Apache 2.0 — see [LICENSE](LICENSE).