From 19665af2055d9aa579c563db348518c22222f9c3 Mon Sep 17 00:00:00 2001 From: Miguel Mendoza Date: Wed, 30 Oct 2024 09:53:36 -0700 Subject: [PATCH] doc: minor changes to doc markdown * Add link from mock/commands/mock-oas.md to the mock-openapi-spec.md page * Add link from transform/index.md to the commands/oas-overlay.md page * Re-structure the oas-overlay.md page to make it more legible --- docs/index.md | 2 +- docs/mock/commands/mock-oas.md | 2 ++ docs/transform/commands/oas-overlay.md | 9 +++++---- docs/transform/index.md | 5 ++++- 4 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/index.md b/docs/index.md index 9a5de13..645aab7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,7 @@ The `apigee-go-gen` CLI tool streamlines your Apigee development experience usin * **[Transformation commands](./transform/index.md)** Easily convert between Apigee's API proxy format and YAML for better readability and management. * **[Template rendering commands](./render/index.md)** Enjoy powerful customization and dynamic configuration options, inspired by the flexibility of Helm using the Go [text/template](https://pkg.go.dev/text/template) engine. -* **[Mock generation command](./mock/commands/mock-oas.md)** Effortlessly create a mock API proxy from your OpenAPI 3.X spec, complete with dynamic response bodies, headers, and status codes. +* **[Mock generation command](./mock/mock-openapi-spec.md)** Effortlessly create a mock API proxy from your OpenAPI 3.X spec, complete with dynamic response bodies, headers, and status codes. By using this tool alongside the [Apigee CLI](https://github.com/apigee/apigeecli), you'll unlock a highly customizable workflow. This is perfect for both streamlined local development and robust CI/CD pipelines. diff --git a/docs/mock/commands/mock-oas.md b/docs/mock/commands/mock-oas.md index b7ee31c..7183b46 100644 --- a/docs/mock/commands/mock-oas.md +++ b/docs/mock/commands/mock-oas.md @@ -27,3 +27,5 @@ The `mock oas` command takes the following parameters: -h, --help help for oas ``` +> See how the mock API proxy bundle works over at the [Mock OpenAPI Spec](../mock-openapi-spec.md) doc page + diff --git a/docs/transform/commands/oas-overlay.md b/docs/transform/commands/oas-overlay.md index d8859af..157ee13 100644 --- a/docs/transform/commands/oas-overlay.md +++ b/docs/transform/commands/oas-overlay.md @@ -24,16 +24,17 @@ The `oas-overlay` command takes the following parameters: * `--overlay` is the path to the OpenAPI Overlay (either as JSON or YAML) * `--spec` (*optional*) is the path to the OpenAPI Spec to transform (either as JSON or YAML) + +* `--output` is the document to be created (either as JSON or YAML) + > The `--spec` parameter is optional. If omitted, the OAS path is read form the `extends` property of the overlay. > In this case, the path is relative to the location of the overlay file itself. -* `--output` is the document to be created (either as JSON or YAML) - -> Full path is created if it does not exist (like `mkdir -p`) -> You may omit the `--output` flags to write to stdout +> You may omit the `--output` flags to write to stdout +> Full path is created if the `--output` does not exist (like `mkdir -p`) diff --git a/docs/transform/index.md b/docs/transform/index.md index cc197e3..5e7f9e0 100644 --- a/docs/transform/index.md +++ b/docs/transform/index.md @@ -34,5 +34,8 @@ The `apigee-go-gen` includes the following set of `transform` commands to help y * [oas2-to-oas3](./commands/oas2-to-oas3.md) - Transforms an OpenAPI 2 spec (also known as Swagger) into OpenAPI 3 -* [resolve-refs](./commands/resolve-refs.md) - Replace external $refs (JSONRefs) in input YAML or JSON doc with actual values +* [resolve-refs](./commands/resolve-refs.md) - Replace external $refs (JSONRefs) in a YAML or JSON doc with actual values + +* [oas-overlay](./commands/oas-overlay.md) - Transforms an Open API spec by applying an [overlay](https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md) file +