Skip to content
This repository was archived by the owner on Dec 8, 2025. It is now read-only.

docs: update examples to use openapi-overlay #15

Merged
ThomasRooney merged 2 commits into from
May 5, 2025
Merged

docs: update examples to use openapi-overlay #15

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
993a014
docs: correct typo
jamietanna May 3, 2025
ea3c7c1
docs: update examples to use `openapi-overlay`
jamietanna May 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,11 @@ go install github.com/speakeasy-api/openapi-overlay@latest

# Usage

The tool provides sub-commands such as `apply`, `validate` and `compare` under the `openapi-overlay` command for working with overlay files. The reccomended 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.
The tool provides sub-commands such as `apply`, `validate` and `compare` under the `openapi-overlay` command for working with overlay files.

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

However, the `openapi-overlay` tool can be used standalone.

For more examples of usage, see [here](https://www.speakeasyapi.dev/docs/openapi/overlays)

Expand All @@ -49,7 +53,7 @@ For more examples of usage, see [here](https://www.speakeasyapi.dev/docs/openapi
The most obvious use-case for this command is applying an overlay to a specification file.

```sh
speakeasy overlay apply --overlay=overlay.yaml --schema=spec.yaml
openapi-overlay apply --overlay=overlay.yaml --schema=spec.yaml
```

If the overlay file has the `extends` key set to a `file://` URL, then the `spec.yaml` file may be omitted.
Expand All @@ -59,15 +63,15 @@ If the overlay file has the `extends` key set to a `file://` URL, then the `spec
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.

```sh
speakeasy overlay validate --overlay=overlay.yaml
openapi-overlay validate --overlay=overlay.yaml
```

## Compare

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

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

the overlay file will be written to a file called `overlay.yaml` with a diagnostic output in the console.
Expand Down
Loading