{"id":48716370,"url":"https://github.com/mimikos-io/mimikos","last_synced_at":"2026-04-19T12:05:13.611Z","repository":{"id":347094903,"uuid":"1190730301","full_name":"mimikos-io/mimikos","owner":"mimikos-io","description":"A deterministic, OpenAPI-driven mock server that generates realistic API responses with zero manual config.","archived":false,"fork":false,"pushed_at":"2026-04-14T06:18:17.000Z","size":556,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T08:34:03.127Z","etag":null,"topics":["api-mocking","api-testing","deterministic","developer-tools","golang","mock-server","openapi","openapi3","schema-driven","test-doubles","zero-config"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mimikos-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-24T15:06:40.000Z","updated_at":"2026-04-14T06:18:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mimikos-io/mimikos","commit_stats":null,"previous_names":["mimikos-io/mimikos"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/mimikos-io/mimikos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimikos-io%2Fmimikos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimikos-io%2Fmimikos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimikos-io%2Fmimikos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimikos-io%2Fmimikos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mimikos-io","download_url":"https://codeload.github.com/mimikos-io/mimikos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimikos-io%2Fmimikos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32005839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-mocking","api-testing","deterministic","developer-tools","golang","mock-server","openapi","openapi3","schema-driven","test-doubles","zero-config"],"created_at":"2026-04-11T17:18:17.809Z","updated_at":"2026-04-19T12:05:13.585Z","avatar_url":"https://github.com/mimikos-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎭 Mimikos\n\n**Zero-config mock server from OpenAPI specs**\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Go Version](https://img.shields.io/badge/Go-1.25+-blue.svg)](https://golang.org)\n[![Status](https://img.shields.io/badge/Status-Alpha-blue.svg)]()\n[![Go Report Card](https://goreportcard.com/badge/github.com/mimikos-io/mimikos)](https://goreportcard.com/report/github.com/mimikos-io/mimikos)\n[![codecov](https://codecov.io/github/mimikos-io/mimikos/graph/badge.svg?token=WZ4E26OXM8)](https://codecov.io/github/mimikos-io/mimikos)\n\n---\n\n## What It Does\n\nPoint it at an OpenAPI spec. Get a working mock server:\n\n- Generates realistic, schema-valid responses for every endpoint\n- Produces the same response for the same request, every time\n- **Stateful mode** — POST creates resources, GET retrieves them, DELETE removes them\n- Classifies endpoints automatically — no mock definitions to write\n- Validates incoming requests and returns useful error diagnostics\n- Works with OpenAPI 3.0 and 3.1\n\n---\n\n## Why Mimikos\n\n**The Problem:**\nMock servers either require you to hand-write every response, or generate shallow, random data that drifts from your\nactual API. When the spec changes, your mocks break — or worse, silently become wrong.\n\n**What You Get:**\nA single binary that reads your OpenAPI spec and serves realistic responses immediately. No configuration files. No\nmock definitions. No maintenance when your API evolves.\n\n**Key Benefits:**\n\n- **Zero configuration** — your OpenAPI spec is the only input\n- **Deterministic** — same request always returns the same response, safe for snapshot testing\n- **Schema evolution safe** — update your spec, responses update automatically, existing field values stay stable\n- **Realistic data** — field-aware generation produces emails for `email`, names for `name`, URLs for `url`\n- **Useful errors** — invalid requests get RFC 7807 Problem Details with field-level diagnostics\n- **Single binary** — no runtime dependencies, no containers, no services to manage\n\n---\n\n## Installation\n\n**Go install** (requires Go 1.25+):\n\n```bash\ngo install github.com/mimikos-io/mimikos/cmd/mimikos@latest\n```\n\n**Pre-built binaries:**\n\nDownload from [GitHub Releases](https://github.com/mimikos-io/mimikos/releases) for Linux, macOS, and Windows:\n\n```bash\n# macOS / Linux\ntar -xzf mimikos_\u003cos\u003e_\u003carch\u003e.tar.gz\nxattr -d com.apple.quarantine mimikos  # macOS only — remove Gatekeeper quarantine\nsudo mv mimikos /usr/local/bin/\n\n# Verify\nmimikos --version\n```\n\n\u003e **macOS note:** The pre-built binary is not code-signed, so macOS Gatekeeper will block it on first run. The `xattr`\n\u003e command above removes the quarantine flag. Alternatively, install via `go install` which builds from source and avoids\n\u003e this entirely.\n\nOn Windows, download the `.zip`, extract `mimikos.exe`, and add it to your `PATH`.\n\n---\n\n## Quick Start\n\n```bash\nmimikos start petstore.yaml\n```\n\n```\n🎭 mimikos 0.2.0\nSpec: Petstore (OpenAPI 3.1.0)\nOperations: 5 endpoints classified\n\n  GET     /pets                           → list       high\n  POST    /pets                           → create     high\n  GET     /pets/{petId}                   → fetch      high\n  DELETE  /pets/{petId}                   → delete     high\n  PATCH   /pets/{petId}                   → update     high\n\nListening on :8080 (deterministic mode, strict=false)\n```\n\n```bash\ncurl http://localhost:8080/pets\ncurl http://localhost:8080/pets/42\ncurl -X POST http://localhost:8080/pets \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Buddy\"}'\n```\n\n---\n\n## Stateful Mode\n\nBy default, Mimikos runs in **deterministic mode** — the same request always returns the same generated response. For\ntesting workflows that depend on state (create → read → update → delete), use **stateful mode**:\n\n```bash\nmimikos start --mode stateful petstore.yaml\n```\n\nIn stateful mode:\n\n- **POST** creates a resource and stores it in memory\n- **GET** (item) retrieves a previously created resource, or 404 if it doesn't exist\n- **GET** (list) returns all created resources of that type\n- **PUT/PATCH** updates a stored resource (shallow merge)\n- **DELETE** removes a resource from the store\n\n```bash\n# Create a pet — returns 201 with a generated resource\ncurl -s -X POST http://localhost:8080/pets \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Buddy\"}'\n# → {\"id\": 7, \"name\": \"Buddy\", \"tag\": \"...\", ...}\n\n# Use the returned ID to fetch\ncurl http://localhost:8080/pets/7\n# → 200 with the stored pet\n\n# List all pets\ncurl http://localhost:8080/pets\n# → 200 with array of created pets\n\n# Delete\ncurl -X DELETE http://localhost:8080/pets/7\n# → 204\n\n# Fetch after delete\ncurl http://localhost:8080/pets/7\n# → 404\n```\n\nResources are stored in memory with LRU eviction. Use `--max-resources` to control capacity (default: 10,000).\nRestarting the server clears all state.\n\n---\n\n## CLI Reference\n\n```\nmimikos start [flags] \u003cspec-path\u003e\n```\n\n| Flag              | Description                                          | Default         |\n|-------------------|------------------------------------------------------|-----------------|\n| `--port`          | Server port                                          | `8080`          |\n| `--mode`          | Operating mode: `deterministic`, `stateful`          | `deterministic` |\n| `--max-resources` | Max stored resources in stateful mode (LRU eviction) | `10000`         |\n| `--strict`        | Return 500 if generated response fails validation    | `false`         |\n| `--max-depth`     | Max depth for nested/circular schemas                | `3`             |\n| `--log-level`     | Logging verbosity (debug, info, warn, error)         | `info`          |\n\n**Request an error response:**\n\n```bash\ncurl -H \"X-Mimikos-Status: 404\" http://localhost:8080/pets/42\n```\n\nReturns the error response defined in your spec for that status code, or an RFC 7807 fallback if no schema is defined.\n\n---\n\n## Versioning\n\nThis project follows [Semantic Versioning](https://semver.org/):\n\n- **0.x.y versions** indicate **initial development**:\n    - The API and output format may change between minor versions\n    - Pin a version that works for your environment\n\n- **1.0.0 and above** will indicate **stable output guarantees**:\n    - MAJOR version for changes that alter generated responses\n    - MINOR version for new features with backward-compatible output\n    - PATCH version for bug fixes\n\nThe current version is in early development. Response output may change between releases until 1.0.0.\n\n---\n\n## Development\n\n```bash\nmake build          # Build binary\nmake run test       # Run all tests\nmake run test unit  # Unit tests only\nmake check          # Lint + vet + test\nmake fix            # Auto-format + tidy\n```\n\n---\n\n## Requirements\n\n- Go 1.25+ (for building from source)\n\n---\n\n## Links\n\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md) — release history\n- **Issues**: https://github.com/mimikos-io/mimikos/issues\n\n---\n\n## License\n\nApache 2.0 — See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmimikos-io%2Fmimikos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmimikos-io%2Fmimikos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmimikos-io%2Fmimikos/lists"}