Merge pull request #27 from jeremyfiel/patch-1

fix typo, style guide updates

.gitignore

@@ -23,4 +23,5 @@ dist
 dist/
 site
 venv
-.venv
+.venv
+__pycache__

cmd/apigee-go-gen/mock/oas/cmd.go

@@ -28,7 +28,7 @@ var debug = flags.NewBool(false)
 
 var Cmd = &cobra.Command{
 	Use:   "oas",
-	Short: "Generate a mock API proxy from an OpenAPI 3.X spec",
+	Short: "Generate a mock API proxy from an OpenAPI 3.X Description",
 	Long:  Usage(),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return mock.GenerateMockProxyBundle(string(input), string(output), bool(debug))
@@ -37,7 +37,7 @@ var Cmd = &cobra.Command{
 
 func init() {
 	Cmd.Flags().SortFlags = false
-	Cmd.Flags().VarP(&input, "input", "i", `path to OpenAPI spec (e.g. "./path/to/spec.yaml")`)
+	Cmd.Flags().VarP(&input, "input", "i", `path to OpenAPI Description (e.g. "./path/to/openapi.yaml")`)
 	Cmd.Flags().VarP(&output, "output", "o", `output directory or zip file (e.g. "./path/to/apiproxy.zip")`)
 	Cmd.Flags().VarP(&debug, "debug", "", `prints rendered template before creating API proxy bundle"`)
 
@@ -49,7 +49,7 @@ func init() {
 
 func Usage() string {
 	usageText := `
-This command generates a mock API proxy bundle from an OpenAPI 3.X Spec.
+This command generates a mock API proxy bundle from an OpenAPI 3.X Description.
 
 The mock API proxy includes the following features:
 

cmd/apigee-go-gen/render/apiproxy/cmd.go

@@ -67,7 +67,7 @@ func init() {
 	Cmd.Flags().Var(&setValueStr, "set-string", `sets key=value (string), e.g. "base_path=/v1/hello" `)
 	Cmd.Flags().Var(&setValueFile, "values", `sets keys/values from YAML file, e.g. "./values.yaml"`)
 	Cmd.Flags().Var(&setFile, "set-file", `sets key=value where value is the content of a file, e.g. "my_data=./from/file.txt"`)
-	Cmd.Flags().Var(&setOAS, "set-oas", `sets key=value where value is an OpenAPI spec, e.g. "my_spec=./petstore.yaml"`)
+	Cmd.Flags().Var(&setOAS, "set-oas", `sets key=value where value is an OpenAPI Description, e.g. "my_spec=./petstore.yaml"`)
 	Cmd.Flags().Var(&setGRPC, "set-grpc", `sets key=value where value is a gRPC proto, e.g. "my_proto=./greeter.proto"`)
 	Cmd.Flags().Var(&setGraphQL, "set-graphql", `sets key=value where value is a GraphQL schema, e.g. "my_schema=./resorts.graphql"`)
 	Cmd.Flags().Var(&setJSON, "set-json", `sets key=value where value is JSON, e.g. 'servers=["server1","server2"]'`)

cmd/apigee-go-gen/render/sharedflow/cmd.go

@@ -67,7 +67,7 @@ func init() {
 	Cmd.Flags().Var(&setValueStr, "set-string", `sets key=value (string), e.g. "base_path=/v1/hello" `)
 	Cmd.Flags().Var(&setValueFile, "values", `sets keys/values from YAML file, e.g. "./values.yaml"`)
 	Cmd.Flags().Var(&setFile, "set-file", `sets key=value where value is the content of a file, e.g. "my_data=./from/file.txt"`)
-	Cmd.Flags().Var(&setOAS, "set-oas", `sets key=value where value is an OpenAPI spec, e.g. "my_spec=./petstore.yaml"`)
+	Cmd.Flags().Var(&setOAS, "set-oas", `sets key=value where value is an OpenAPI Description, e.g. "my_spec=./petstore.yaml"`)
 	Cmd.Flags().Var(&setGRPC, "set-grpc", `sets key=value where value is a gRPC proto, e.g. "my_proto=./greeter.proto"`)
 	Cmd.Flags().Var(&setGraphQL, "set-graphql", `sets key=value where value is a GraphQL schema, e.g. "my_schema=./resorts.graphql"`)
 	Cmd.Flags().Var(&setJSON, "set-json", `sets key=value where value is JSON, e.g. 'servers=["server1","server2"]'`)

cmd/apigee-go-gen/render/template/cmd.go

@@ -57,7 +57,7 @@ func init() {
 	Cmd.Flags().Var(&setValueStr, "set-string", `sets key=value (string), e.g. "base_path=/v1/hello" `)
 	Cmd.Flags().Var(&setValueFile, "values", `sets keys/values from YAML file, e.g. "./values.yaml"`)
 	Cmd.Flags().Var(&setFile, "set-file", `sets key=value where value is the content of a file, e.g. "my_data=./from/file.txt"`)
-	Cmd.Flags().Var(&setOAS, "set-oas", `sets key=value where value is an OpenAPI spec, e.g. "my_spec=./petstore.yaml"`)
+	Cmd.Flags().Var(&setOAS, "set-oas", `sets key=value where value is an OpenAPI Description, e.g. "my_spec=./petstore.yaml"`)
 	Cmd.Flags().Var(&setGRPC, "set-grpc", `sets key=value where value is a gRPC proto, e.g. "my_proto=./greeter.proto"`)
 	Cmd.Flags().Var(&setGraphQL, "set-graphql", `sets key=value where value is a GraphQL schema, e.g. "my_schema=./resorts.graphql"`)
 	Cmd.Flags().Var(&setJSON, "set-json", `sets key=value where value is JSON, e.g. 'servers=["server1","server2"]'`)

cmd/apigee-go-gen/transform/oas-overlay/cmd.go

@@ -26,7 +26,7 @@ var output flags.String
 
 var Cmd = &cobra.Command{
 	Use:   "oas-overlay",
-	Short: "Transforms Open API spec by applying overlay file",
+	Short: "Transforms OpenAPI Description by applying Overlay file",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return utils.OASOverlay(string(overlay), string(spec), string(output))
 	},
@@ -35,8 +35,8 @@ var Cmd = &cobra.Command{
 func init() {
 
 	Cmd.Flags().SortFlags = false
-	Cmd.Flags().VarP(&spec, "spec", "s", "path to OpenAPI spec file (optional)")
-	Cmd.Flags().VarP(&overlay, "overlay", "", "path to overlay file")
+	Cmd.Flags().VarP(&spec, "spec", "s", "path to OpenAPI Description file (optional)")
+	Cmd.Flags().VarP(&overlay, "overlay", "", "path to Overlay file")
 	Cmd.Flags().VarP(&output, "output", "o", "path to output file, or omit to use stdout")
 
 	_ = Cmd.MarkFlagRequired("overlay")

cmd/apigee-go-gen/transform/oas2-to-oas3/cmd.go

@@ -26,7 +26,7 @@ var allowCycles = flags.NewBool(false)
 
 var Cmd = &cobra.Command{
 	Use:   "oas2-to-oas3",
-	Short: "Transforms the input OpenAPI 2 spec into OpenAPI 3 spec",
+	Short: "Transforms the input OpenAPI 2 Description into an OpenAPI 3 Description",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return utils.OAS2FileToOAS3File(string(input), string(output), bool(allowCycles))
 	},

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/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.
+* **[Mock generation command](./mock/mock-openapi-description.md)** Effortlessly create a mock API proxy from your OpenAPI 3.X Description, 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.
 
@@ -59,8 +59,8 @@ This approach has the potential to address the current challenges, offering:
 - [x] **Faster time to production** 
 > Leverage Apigee community templates to save time and resources.
 
-- [x] **Stay in sync with API specs** 
-> Auto-update templated API Proxies to stay in sync with the spec, while preserving customizations.
+- [x] **Stay in sync with API descriptions**
+> Auto-update templated API Proxies to stay in sync with the api description, while preserving customizations.
 
 ## Support
 

docs/mock/commands/mock-oas.md

@@ -15,17 +15,17 @@
   limitations under the License.
 -->
 
-This command generates a mock API proxy bundle from your OpenAPI 3 specification.  
+This command generates a mock API proxy bundle from your OpenAPI 3 Description.  
 
 ## Usage
 
 The `mock oas` command takes the following parameters:
 
 ```text
-  -i, --input string    path to OpenAPI spec (e.g. "./path/to/spec.yaml")
+  -i, --input string    path to OpenAPI Description (e.g. "./path/to/openapi.yaml")
   -o, --output string   output directory or zip file (e.g. "./path/to/apiproxy.zip")
   -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
+> See how the mock API proxy bundle works over at the [Mock OpenAPI Description](../mock-openapi-description.md) doc page
 

docs/mock/mock-openapi-spec.md → docs/mock/mock-openapi-description.md

@@ -1,4 +1,4 @@
-# Mock OpenAPI Spec
+# Mock OpenAPI Description
 <!--
   Copyright 2024 Google LLC
 
@@ -15,7 +15,7 @@
   limitations under the License.
 -->
 
-You can use the [mock oas](./commands/mock-oas.md) command to create a mock API proxy from your OpenAPI 3 specification, allowing you to simulate API behavior without a real backend. 
+You can use the [mock oas](./commands/mock-oas.md) command to create a mock API proxy from your OpenAPI 3 Description, allowing you to simulate API behavior without a real backend. 
 
 ## Examples
 
@@ -42,9 +42,9 @@ apigee-go-gen mock oas \
 
 The generated mock API proxy supports the following features.
 
-### :white_check_mark: Base Path from Spec
+### :white_check_mark: Base Path from OAS Description
 
-The `Base Path` for the mock API proxy is derived from the first element of the [servers](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#oas-servers) array in your OpenAPI spec.
+The `Base Path` for the mock API proxy is derived from the first element of the [servers](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#oas-servers) array in your OpenAPI Description.
 
 For example, if your server array looks like this:
 
@@ -73,7 +73,7 @@ This built-in CORS support ensures that your mock API behaves like a real API in
 ### :white_check_mark: Request Validation
 
 
-By default, the mock API proxy validates the incoming requests against your specification. 
+By default, the mock API proxy validates the incoming requests against your description.
 This ensures that the HTTP headers, query parameters, and request body all conform to the defined rules.
 
 This helps you catch errors in your client code early on.
@@ -95,7 +95,7 @@ The mock API proxy automatically generates different status codes for your mock
 **Want more control?** You can use headers to select response the status code:
 
 * **Specific status code:** Use the `Mock-Status` header in your request and set it to the desired code (e.g., `Mock-Status: 404`).
-* **Random status code:** Use the `Mock-Fuzz: true` header to get a random status code from your spec.
+* **Random status code:** Use the `Mock-Fuzz: true` header to get a random status code from your description.
 
 If you use both `Mock-Status` and `Mock-Fuzz`, `Mock-Status` takes precedence.
 
@@ -116,7 +116,7 @@ If you use both `Accept` and `Mock-Fuzz`, the `Accept` header will take preceden
 
 ### :white_check_mark: Dynamic Response Body
 
-The mock API proxy can generate realistic response bodies based on your OpenAPI spec.
+The mock API proxy can generate realistic response bodies based on your OpenAPI Description.
 
 Here's how it determines what to send back for any particular operation's response (in order):
 
@@ -184,29 +184,29 @@ The following fields are supported when generating examples from a JSON schema:
     * `minLength`, `maxLength` fields - string length chosen randomly between these values
 * `integer` type
     * `minimum`, `maximum` fields - a random integer value chosen randomly between these values
-    * `exclusiveMinimuim` field (boolean, JSON-Schema 4)
-    * `exclusiveMaximum` field  (boolean, JSON-Schema 4)
+    * `exclusiveMinimum` field (boolean, JSON-Schema 4, number, JSON Schema 7 or greater)
+    * `exclusiveMaximum` field  (boolean, JSON-Schema 4, number, JSON Schema 7 or greater)
     * `multipleOf` field
 * `number` type
     * `minimum`, `maximum` fields - a random float value chosen randomly between these values
-    * `exclusiveMinimuim` field (boolean, JSON-Schema 4)
-    * `exclusiveMaximum` field  (boolean, JSON-Schema 4)
+    * `exclusiveMinimum` field (boolean, JSON-Schema 4, number, JSON Schema 7 or greater)
+    * `exclusiveMaximum` field  (boolean, JSON-Schema 4, number, JSON Schema 7 or greater)
     * `multipleOf` field
 
 Markdown
-## Enriching your OpenAPI Spec with Examples
+## Enriching your OpenAPI Description with Examples
 
-Sometimes, your OpenAPI specification might be missing response examples or schemas. In other cases, the examples might be very large and difficult to include directly in the spec.  Overlays provide a solution for these situations.
+Sometimes, your OpenAPI Description might be missing response examples or schemas. In other cases, the examples might be very large and difficult to include directly in the description. Overlays provide a solution for these situations.
 
-**What is an overlay?**
+**What is an Overlay?**
 
-An overlay is a separate file that allows you to add or modify information in your existing OpenAPI spec. This is useful for adding examples, schemas, or any other data that you want to keep separate from your main specification file. To learn more about how overlays work, you can refer to the [overlay specification](https://spec.openapis.org/overlay/latest.html).
+An Overlay is a separate file that allows you to add or modify information in your existing OpenAPI Description. This is useful for adding examples, schemas, or any other data that you want to keep separate from your main description file. To learn more about how Overlays work, you can refer to the [Overlay Specification](https://spec.openapis.org/overlay/latest.html).
 
-**How to use an overlay**
+**How to use an Overlay**
 
-Here's how you can use an overlay to add a static example to an API operation:
+Here's how you can use an Overlay to add a static example to an API operation:
 
-1.  **Create an overlay file:** This file defines the changes you want to make to your OpenAPI spec. Here's an example that adds a sample response for the `/pet/findByStatus` operation:
+1.  **Create an Overlay file:** This file defines the changes you want to make to your OpenAPI Description. Here's an example that adds a sample response for the `/pet/findByStatus` operation:
 
     ```yaml
     overlay: 1.0.0
@@ -218,20 +218,23 @@ Here's how you can use an overlay to add a static example to an API operation:
         update:
           content:
             'application/json':
-              example:
-                {
-                  "id": 1,
-                  "photoUrls": [],
-                  "name": "Rin Tin Tin",
-                  "category": {
-                    "id": 1,
-                    "name": "Dog"
-                  }
-                }
+              examples:
+                findByStatus:
+                  value:
+                    {
+                      "id": 1,
+                      "photoUrls": [],
+                      "name": "Rin Tin Tin",
+                      "category": {
+                        "id": 1,
+                        "name": "Dog"
+                      }
+                    }
+
     ```
 
 
-2.  **Apply the overlay to your OpenAPI spec:** Use the `apigee-go-gen` tool to combine your overlay file with your OpenAPI spec:
+2.  **Apply the Overlay to your OpenAPI Description:** Use the `apigee-go-gen` tool to combine your Overlay file with your OpenAPI Description:
 
     ```bash
     apigee-go-gen transform oas-overlay \
@@ -240,12 +243,12 @@ Here's how you can use an overlay to add a static example to an API operation:
       --output ./out/specs/petstore-overlaid.yaml
     ```
 
-3.  **Generate a mock API proxy:** You can now use the updated OpenAPI spec to generate a mock API proxy in Apigee:
+3.  **Generate a mock API proxy:** You can now use the updated OpenAPI Description to generate a mock API proxy in Apigee:
 
     ```bash
     apigee-go-gen mock oas \
         --input ./out/specs/petstore-overlaid.yaml \
         --output ./out/mock-apiproxies/petstore.zip
     ```
 
-This process allows you to manage your OpenAPI spec more effectively by keeping your examples and other supplementary data in separate files.
+This process allows you to manage your OpenAPI Description more effectively by keeping your examples and other supplementary data in separate files.

docs/render/commands/render-apiproxy.md

@@ -21,13 +21,13 @@ Under the hood, this command combines the [render template](./render-template.md
 
 Using a template based workflow offers several advantages over working directly with the traditional Apigee API proxy bundle. e.g.
 
-- [x] **Enhanced Customization**  
+- [x] **Enhanced Customization**
 > Tweak your API proxy configurations with the readability of YAML.
 
-- [x] **Seamless Spec Synchronization**  
-> Template-generated API proxy bundles can be easily synced with your specs by re-generating them when changes occur.
+- [x] **Seamless OAS Description Synchronization**
+> Template-generated API proxy bundles can be easily synced with your descriptions by re-generating them when changes occur.
 
-- [x] **Streamline Your Development**  
+- [x] **Streamline Your Development**
 > YAML's versatility allows for easy version control, automation, and integration into CI/CD pipelines.
 
 ## Usage
@@ -46,7 +46,7 @@ The `render apiproxy` command takes the following parameters:
       --set-string string        sets key=value (string), e.g. "base_path=/v1/hello" 
       --values string            sets keys/values from YAML file, e.g. "./values.yaml"
       --set-file string          sets key=value where value is the content of a file, e.g. "my_data=./from/file.txt"
-      --set-oas string           sets key=value where value is an OpenAPI spec, e.g. "my_spec=./petstore.yaml"
+      --set-oas string           sets key=value where value is an OpenAPI Description, e.g. "my_spec=./petstore.yaml"
       --set-grpc string          sets key=value where value is a gRPC proto, e.g. "my_proto=./greeter.proto"
       --set-graphql string       sets key=value where value is a GraphQL schema, e.g. "my_schema=./resorts.graphql"
       --set-json string          sets key=value where value is JSON, e.g. 'servers=["server1","server2"]'

docs/render/commands/render-sharedflow.md

@@ -38,7 +38,7 @@ The `render sharedflow` command takes the following parameters:
       --set-string string        sets key=value (string), e.g. "base_path=/v1/hello" 
       --values string            sets keys/values from YAML file, e.g. "./values.yaml"
       --set-file string          sets key=value where value is the content of a file, e.g. "my_data=./from/file.txt"
-      --set-oas string           sets key=value where value is an OpenAPI spec, e.g. "my_spec=./petstore.yaml"
+      --set-oas string           sets key=value where value is an OpenAPI Description, e.g. "my_spec=./petstore.yaml"
       --set-grpc string          sets key=value where value is a gRPC proto, e.g. "my_proto=./greeter.proto"
       --set-graphql string       sets key=value where value is a GraphQL schema, e.g. "my_schema=./resorts.graphql"
       --set-json string          sets key=value where value is JSON, e.g. 'servers=["server1","server2"]'

docs/render/commands/render-template.md

@@ -35,7 +35,7 @@ The `render template` command takes the following  parameters:
     --set-string string    sets key=value (string), e.g. "base_path=/v1/hello"
     --values string        sets keys/values from YAML file, e.g. "./values.yaml"
     --set-file string      sets key=value where value is the content of a file, e.g. "my_data=./from/file.txt"
-    --set-oas string       sets key=value where value is an OpenAPI spec, e.g. "my_spec=./petstore.yaml"
+    --set-oas string       sets key=value where value is an OpenAPI Description, e.g. "my_spec=./petstore.yaml"
     --set-grpc string      sets key=value where value is a gRPC proto, e.g. "my_proto=./greeter.proto"
     --set-graphql string   sets key=value where value is a GraphQL schema, e.g. "my_schema=./resorts.graphql"
     --set-json string      sets key=value where value is JSON, e.g. 'servers=["server1","server2"]'