{"id":22089844,"url":"https://github.com/speakeasy-api/openapi-overlay","last_synced_at":"2025-07-24T19:31:34.347Z","repository":{"id":205677313,"uuid":"704271465","full_name":"speakeasy-api/openapi-overlay","owner":"speakeasy-api","description":"An implementation of the OpenAPI Overlay specification","archived":false,"fork":false,"pushed_at":"2024-11-11T13:50:26.000Z","size":78,"stargazers_count":19,"open_issues_count":2,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-11-30T19:44:51.517Z","etag":null,"topics":["jsonpath","openapi","overlay","sdk"],"latest_commit_sha":null,"homepage":"https://www.speakeasyapi.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/speakeasy-api.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-12T23:09:09.000Z","updated_at":"2024-11-11T13:50:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"2acb0f02-a8bc-4ebe-99c9-6ad75a9e8685","html_url":"https://github.com/speakeasy-api/openapi-overlay","commit_stats":null,"previous_names":["speakeasy-api/openapi-overlay","speakeasy-api/openapi-specedit"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fopenapi-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fopenapi-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fopenapi-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fopenapi-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/speakeasy-api","download_url":"https://codeload.github.com/speakeasy-api/openapi-overlay/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227470069,"owners_count":17778930,"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":["jsonpath","openapi","overlay","sdk"],"created_at":"2024-12-01T02:14:27.555Z","updated_at":"2025-07-24T19:31:34.334Z","avatar_url":"https://github.com/speakeasy-api.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![made-with-Go](https://img.shields.io/badge/Made%20with-Go-1f425f.svg)](https://go.dev/)\n[![Go Report Card](https://goreportcard.com/badge/github.com/speakeasy-api/openapi-overlay)](https://goreportcard.com/report/github.com/speakeasy-api/openapi-overlay)\n[![GoDoc](https://godoc.org/github.com/speakeasy-api/openapi-overlay?status.svg)](https://godoc.org/github.com/speakeasy-api/openapi-overlay)\n\n\n# OpenAPI Overlay\n\n\u003ca href=\"https://speakeasy.com/openapi/overlays\"\u003e\u003cimg src=\"https://custom-icon-badges.demolab.com/badge/-Overlay%20Reference-212015?style=for-the-badge\u0026logoColor=FBE331\u0026logo=speakeasy\u0026labelColor=545454\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://join.slack.com/t/speakeasy-dev/shared_invite/zt-1cwb3flxz-lS5SyZxAsF_3NOq5xc8Cjw\"\u003e\u003cimg src=\"https://img.shields.io/static/v1?label=Slack\u0026message=Join\u0026color=7289da\u0026style=for-the-badge\" /\u003e\u003c/a\u003e\n\n\u003e ⚠️ This an alpha implementation. If you'd like to discuss a production use case please join the Speakeasy [slack](https://join.slack.com/t/speakeasy-dev/shared_invite/zt-1df0lalk5-HCAlpcQiqPw8vGukQWhexw).\n\nThis is an implementation of the [OpenAPI Overlay\nSpecification](https://github.com/OAI/Overlay-Specification/blob/3f398c6/versions/1.0.0.md)\n(2023-10-12). This specification defines a means of editing a OpenAPI\nSpecification file by applying a list of actions. Each action is either a remove\naction that prunes nodes or an update that merges a value into nodes. The nodes\nimpacted are selected by a target expression which uses JSONPath.\n\nThe specification itself says very little about the input file to be modified or\nthe output file. The presumed intention is that the input and output be an\nOpenAPI Specification, but that is not required.\n\nIn many ways, this is similar to [JSONPatch](https://jsonpatch.com/), but\nwithout the requirement to use a single explicit path for each operation. This\nallows the creator of an overlay file to apply a single modification to a large\nnumber of nodes in the file within a single operation.\n\nThis tool uses [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) to parse\nthe input, which implements YAML v1.2 parsing. YAML v1.2 is a superset of JSON,\nso it should be able to parse either YAML or JSON with the same parser.\n\n# Installation\n\nInstall it with the `go install` command:\n\n```sh\ngo install github.com/speakeasy-api/openapi-overlay@latest\n```\n\n# Usage\n\nThe tool provides sub-commands such as `apply`, `validate` and `compare` under the `openapi-overlay` command for working with overlay files.\n\nThe recommended usage pattern is through Speakeasy CLI command `speakeasy overlay`. Please see [here](https://www.speakeasyapi.dev/docs/speakeasy-cli/overlay/README) for CLI installation and usage documentation.\n\nHowever, the `openapi-overlay` tool can be used standalone.\n\nFor more examples of usage, see [here](https://www.speakeasyapi.dev/docs/openapi/overlays)\n\n## Apply\n\nThe most obvious use-case for this command is applying an overlay to a specification file.\n\n```sh\nopenapi-overlay apply --overlay=overlay.yaml --schema=spec.yaml\n```\n\nIf the overlay file has the `extends` key set to a `file://` URL, then the `spec.yaml` file may be omitted.\n\n## Validate\n\nA command is provided to perform basic validation of the overlay file itself. It will not tell you whether it will apply correctly or whether the application will generate a valid OpenAPI specification. Rather, it is limited to just telling you when the spec follows the OpenAPI Overlay Specification correctly: all required fields are present and have valid values.\n\n```sh\nopenapi-overlay validate --overlay=overlay.yaml\n```\n\n## Compare\n\nFinally, a tool is provided that will generate an OpenAPI Overlay specification from two input files.\n\n```sh\nopenapi-overlay compare --before=spec1.yaml --after=spec2.yaml --out=overlay.yaml\n```\n\nthe overlay file will be written to a file called `overlay.yaml` with a diagnostic output in the console.\n\n# Other Notes\n\nThis tool works with either YAML or JSON input files, but always outputs YAML at this time.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeakeasy-api%2Fopenapi-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspeakeasy-api%2Fopenapi-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeakeasy-api%2Fopenapi-overlay/lists"}