{"id":38964128,"url":"https://github.com/gcatanese/openapi-native-mock-server","last_synced_at":"2026-01-17T16:27:39.416Z","repository":{"id":204001886,"uuid":"710680390","full_name":"gcatanese/openapi-native-mock-server","owner":"gcatanese","description":"Generate mock responses based on your OpenAPI specification. No dependencies. Lightweight, fast, simple.","archived":false,"fork":false,"pushed_at":"2025-12-22T13:30:41.000Z","size":50058,"stargazers_count":1,"open_issues_count":14,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-24T00:27:07.271Z","etag":null,"topics":["mock-server","openapi","openapi3","openapi31","testing"],"latest_commit_sha":null,"homepage":"","language":"Java","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/gcatanese.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2023-10-27T07:58:04.000Z","updated_at":"2025-03-30T13:40:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"91edc949-6370-4457-aef7-65fe2390c078","html_url":"https://github.com/gcatanese/openapi-native-mock-server","commit_stats":null,"previous_names":["gcatanese/openapi-native-mock-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gcatanese/openapi-native-mock-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcatanese%2Fopenapi-native-mock-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcatanese%2Fopenapi-native-mock-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcatanese%2Fopenapi-native-mock-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcatanese%2Fopenapi-native-mock-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gcatanese","download_url":"https://codeload.github.com/gcatanese/openapi-native-mock-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcatanese%2Fopenapi-native-mock-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28511864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["mock-server","openapi","openapi3","openapi31","testing"],"created_at":"2026-01-17T16:27:39.326Z","updated_at":"2026-01-17T16:27:39.396Z","avatar_url":"https://github.com/gcatanese.png","language":"Java","readme":"# OpenAPI Native Mock Server\n\nLightweight mock server created from an OpenAPI specification. \n\nWhy **native**? Because the request-response interactions are defined within the OpenAPI file, without\nthe need for an additional application or storage (and therefore complexity). No external dependencies.\n\nThe request-response interactions (aka the contracts) are defined by parsing the OpenAPI examples, see [mapping strategies](#how-it-works).\nA fallback response is generated to ensure every request receives always a response.\n\nIt is:\n* **lightweight**: it runs in a single (small) container\n* **fast**: it creates behind the scenes a Go service with a minimal footprint\n* **simple**: it displays the mock expectations on the index page. Inspect the JSON payload of all mocked responses.\n\n## Use cases\n\nIt can be used in different scenarios:\n* you are developing an API SDK and need to implement solid integration testing: try it out with [TestContainers](https://github.com/gcatanese/openapi-testcontainers).\n* you are building APIs and want to help your API consumers during the integration: make a mock server (that implements the API contract) readily available.\n* you are developing an application that uses a third-party API dependency: mock the API to make your development faster and more efficient.\n\n## Usage\n\n### Build and run with Docker\n\nBuild the mock server from your OpenAPI file:\n```docker\ndocker build --build-arg openapifile=/path/openapiFile.yaml -t openapi-native-mock-server .\n```\n\nRun the container:\n```docker\ndocker run --rm -d -p 8080:8080 --name openapi-native-mock-server openapi-native-mock-server\n```\n\nPoint your API requests to the mock server:\n```shell\ncurl -X POST -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"abc\",\"country\":\"abc\"}' \\\n   http://localhost:8080/{your_api_endpoint}\n```\n\n### Build and run from source\n\nBuild the mock server (**Note**: requires Java 11)\n```shell\nmvn package\n```\n\nGenerate the mock server passing the path of the OpenAPI file (i.e. `-i openapi/tmp/openapi.yaml`) and the\nfolder that will contain the mock server source code (i.e. `-o openapi/tmp/go-server`):\n```shell\njava -cp target/openapi-native-mock-server.jar:openapi/cli/openapi-generator-cli.jar \\\n org.openapitools.codegen.OpenAPIGenerator generate -g com.tweesky.cloudtools.codegen.NativeMockServerCodegen \\\n  -i openapi/tmp/openapi.yaml -o openapi/tmp/go-server\n```\n\nRun the mock server (**Note**: requires Go 1.19):\n\n```shell\ncd openapi/tmp/go-server\ngo mod tidy\ngo run .\n```\n\nPoint your API requests to the mock server:\n```shell\ncurl -X POST -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"abc\",\"country\":\"abc\"}' \\\n   http://localhost:8080/{your_api_endpoint}\n```\n\n### Mock server browser\n\nAccess the index page to view the OpenAPI file (which the mock server has been created from) \nand the mock expectations:\n```shell\ncurl http://localhost:8080/index/\n```\nThe `index` page provides a view of the contract interactions, making clear the expectations.\nCheck it out.\n\n![Mock server browser](mock-server.png)\n\n\n## How it works\n\nThe module uses the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) to generate a lightweight \nmock server based on the OpenAPI specification. The request and response examples are found and matched to define the \ninteractions (contract) between the consumer and the producer of the API.  \n\nThe following strategies are applied (in order) to match requests with responses:\n* **match by Contract tag**: do the examples use the vendor extension `x-contract-id`? In this case, match a request with a response example that has the same value\n* **match by Ref name**: match `$ref` request example with a corresponding `$ref` response example, for example \n`create-users-example` would match `create-users-example-200` to define a successful `200` scenario\n* **match by Example name**: find request and response examples that have the same name\n* **generate from Schema**: fallback strategy (when no matching is found): generate the response from the Schema and\nensure every request has at least a response.\n\n\n## References\n\nCheck out the [Contract Testing with OpenAPI](https://beppecatanese.hashnode.dev/contract-testing-with-openapi) to understand challenges and opportunities of Contract Testing with the OpenAPI standard.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgcatanese%2Fopenapi-native-mock-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgcatanese%2Fopenapi-native-mock-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgcatanese%2Fopenapi-native-mock-server/lists"}