{"id":22200276,"url":"https://github.com/znsio/overlays_demo","last_synced_at":"2026-01-04T18:49:52.108Z","repository":{"id":264836082,"uuid":"894420781","full_name":"znsio/overlays_demo","owner":"znsio","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-28T13:30:58.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-01-30T02:44:54.344Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/znsio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-11-26T10:26:02.000Z","updated_at":"2024-11-28T13:31:02.000Z","dependencies_parsed_at":"2024-11-26T11:35:47.278Z","dependency_job_id":"a1ac9b8d-00ab-4d3f-822d-12162ff68e56","html_url":"https://github.com/znsio/overlays_demo","commit_stats":null,"previous_names":["znsio/overlays_demo"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Foverlays_demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Foverlays_demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Foverlays_demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Foverlays_demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/znsio","download_url":"https://codeload.github.com/znsio/overlays_demo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245372219,"owners_count":20604489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-12-02T15:22:11.278Z","updated_at":"2026-01-04T18:49:52.081Z","avatar_url":"https://github.com/znsio.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Specmatic Overlays Demo\n\nThis repository demonstrates the power of overlays (and the support by Specmatic) - a feature that allows you to extend and modify OpenAPI specifications without changing the original contract. This is particularly useful when you need to:\n\n- Add common headers across multiple endpoints\n- Extend security requirements\n- Add new parameters for monitoring or tracing\n- Modify specifications for different environments\n\n## Overview\n\nThe demo consists of three key files:\n- `employees.yaml` - The base OpenAPI specification for an employee service\n- `employees_overlay.yaml` - An overlay that adds required headers for API gateway integration\n- `specmatic.yaml` - Configuration file for Specmatic\n\nThe overlay adds three important headers to the POST /employees endpoint:\n- X-Correlation-ID: For request tracking\n- X-Gateway-Token: For API gateway authentication\n- X-Request-ID: For request tracing\n\n## Documentation\n\nFor a complete understanding of Specmatic overlays, please refer to the [official documentation](https://specmatic.io/documentation/contract_tests.html#overlays).\n\n## Running the Demo\n\nYou can run this demo using Docker, Specmatic Jar or Specmatic Node package. The demo involves two steps:\n1. Starting the stub server\n2. Running the tests to see overlay validation in action\n\n### Using Specmatic Jar\n#### Step 1: Start the stub server\n```shell\njava -jar specmatic.jar stub\n```\n\n#### Step 2: Start the test\n```shell\njava -jar specmatic.jar test --port=9000\n```\n\n\n### Using Docker\n#### Step 1: Start the stub server\n```shell\ndocker run -p=\"9000:9000\" -v=\"./specmatic.yaml:/usr/src/app/specmatic.yaml\" -v=\"./employees.yaml:/usr/src/app/employees.yaml\" -v=\"./employees_overlay.yaml:/usr/src/app/employees_overlay.yaml\" znsio/specmatic stub\n```\n\n\n#### Step 2: Run the tests\n```shell\ndocker run -v=\"./specmatic.yaml:/usr/src/app/specmatic.yaml\" -v=\"./employees.yaml:/usr/src/app/employees.yaml\" -v=\"./employees_overlay.yaml:/usr/src/app/employees_overlay.yaml\" znsio/specmatic test --port=9000 --host=host.docker.internal\n```\n\n### Using NPX\n#### Step 1: Install Specmatic Node package:\n```shell\nnpm install -g specmatic\n```\n\n#### Step 2: Start the stub server:\n```shell\nnpx specmatic stub \n```\n\n#### Step 3: In another terminal, run the tests:\n```bash\nnpx specmatic test \n```\n\n## What to Expect\n\nWhen you run the tests, you'll notice that:\n\n* Specmatic start the `stub` server starts and loads both the base contract and overlay\n* Specmatic loads both the base ccontract and overlay for `test` also, and then requests with all required headers are used for testing.\n* Test requests without the required headers (added by overlay) will fail\n\nThis demonstrates how overlays can enforce additional requirements without modifying the base contract.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fznsio%2Foverlays_demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fznsio%2Foverlays_demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fznsio%2Foverlays_demo/lists"}