Repository files navigation

⚠️ This an alpha implementation. If you'd like to discuss a production use case please join the Speakeasyslack.

This is an implementation of theOpenAPI OverlaySpecification(2023-10-12). This specification defines a means of editing a OpenAPISpecification file by applying a list of actions. Each action is either a removeaction that prunes nodes or an update that merges a value into nodes. The nodesimpacted are selected by a target expression which uses JSONPath.

The specification itself says very little about the input file to be modified orthe output file. The presumed intention is that the input and output be anOpenAPI Specification, but that is not required.

In many ways, this is similar toJSONPatch, butwithout the requirement to use a single explicit path for each operation. Thisallows the creator of an overlay file to apply a single modification to a largenumber of nodes in the file within a single operation.

This tool usesgopkg.in/yaml.v3 to parsethe input, which implements YAML v1.2 parsing. YAML v1.2 is a superset of JSON,so it should be able to parse either YAML or JSON with the same parser.

Install it with thego install command:

go install github.com/speakeasy-api/openapi-overlay@latest

The tool provides sub-commands such asapply,validate andcompare under theopenapi-overlay command for working with overlay files.

The recommended usage pattern is through Speakeasy CLI commandspeakeasy overlay. Please seehere for CLI installation and usage documentation.

However, theopenapi-overlay tool can be used standalone.

For more examples of usage, seehere

The most obvious use-case for this command is applying an overlay to a specification file.

openapi-overlay apply --overlay=overlay.yaml --schema=spec.yaml

If the overlay file has theextends key set to afile:// URL, then thespec.yaml file may be omitted.

A 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.

openapi-overlay validate --overlay=overlay.yaml

Finally, a tool is provided that will generate an OpenAPI Overlay specification from two input files.

openapi-overlay compare --before=spec1.yaml --after=spec2.yaml --out=overlay.yaml

the overlay file will be written to a file calledoverlay.yaml with a diagnostic output in the console.

This tool works with either YAML or JSON input files, but always outputs YAML at this time.