docs: add numbering and headers for navigation, minor edits

doc/openapi-apicurio.md

@@ -1,24 +1,26 @@
-## Using Apicurio with Kuadrant OAS extensions
+# Using Apicurio Studio with Kuadrant OAS extensions
 
-[OpenAPI Extensions](https://swagger.io/docs/specification/openapi-extensions/) can
-be used to describe extra functionality beyond what is covered by the standard OpenAPI
-specification. They typically start with `x-`. Kuadrant OpenAPI extensions start with
-`x-kuadrant`, and allow you to configure Kuadrant policy information along side
-your API.
+You can use [OpenAPI extensions](https://swagger.io/docs/specification/openapi-extensions/) to define extra functionality beyond what is covered by the standard OpenAPI specification. Extensions typically start with the `x-` prefix, for example, `x-codegen`. Kuadrant OpenAPI extensions start with the `x-kuadrant` prefix, and allow you to configure Kuadrant policy information alongside your API.
 
-Apicurio Studio is a UI tool for visualising and editing OpenAPI specifications.
-It has support for visualising security and extensions defined in your spec.
+[Apicurio Studio](https://www.apicur.io/studio) is a UI tool for visualizing and editing OpenAPI designs and definitions, which can visualize security details and custom extensions specified in your OpenAPI definition.
 
-This guide assumes you have Apicurio Studio already running.
-See https://www.apicur.io/studio/ for info on how to install Apicurio Studio.
+## Prerequisites
 
-### Adding extensions to the spec
+- You have Apicurio Studio installed and running. For more information, see the [Apicurio Studio documentation](https://www.apicur.io/studio/docs). 
 
-Open or import your OpenAPI spec in the Apicurio Studio UI.
-You can modify the source of the spec from the UI.
-There are a few different configuration and extension points supported by Apicurio Studio, and also supported by the `kuadrantctl` cli.
+## Procedure 
 
-To generate a [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) for the API, add the following `x-kuadrant` block to your spec in the UI, replacing values to match your APIs details and the location of your Gateway.
+### Step 1 - Access your OpenAPI definition in Apicurio Studio
+
+Open or import your OpenAPI definition in Apicurio Studio. On the **Design** tab, select the **VENDOR-EXTENSiONS** section to add an extension. Alternatively, you can use the **Source** tab to edit the API definition directly.
+
+### Step 2 - Add Kuadrant extensions to your API definition
+
+The following configuration and extension points are supported by Apicurio Studio and the `kuadrantctl` CLI:
+
+#### Generate an HTTP route
+
+To generate an [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) for the API, add the following `x-kuadrant` block to your API definition in Apicurio Studio, replacing values to match your API details and the location of your Gateway:
 
 ```yaml
 info:
@@ -34,11 +36,11 @@ info:
  kind: Gateway
 ```
 
-See [this guide](./generate-gateway-api-httproute.md) for more info on generating a HTTPRoute.
+For more details, see [Generate Gateway API HTTPRoute object from OpenAPI 3](./generate-gateway-api-httproute.md).
+
+#### Generate an AuthPolicy
 
-To generate an [AuthPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/auth/), add a `securityScheme` to the components block.
-This `securityScheme` requires that an API key header is set.
-Although securityScheme is not an OpenAPI extension, it is used by `kuadrantctl` like the other extensions mentioned here.
+To generate an [AuthPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/auth/), add a `securityScheme` to the `components` block in your API definition. The following `securityScheme` requires that an API key header is set:
 
 ```yaml
  securitySchemes:
@@ -48,14 +50,17 @@ Although securityScheme is not an OpenAPI extension, it is used by `kuadrantctl`
  in: header
 ```
 
-When added, the UI will display this in the security schemes section:
+Although `securityScheme` is not an OpenAPI extension, it is used by `kuadrantctl` like the other extensions mentioned in this document.
+
+When added, Apicurio Studio will display the following update in the **SECURITY SCHEMES** section:
 
 ![Apicurio security requirements](./images/apicurio-security-scheme-apikey.png)
 
-See [this guide](./generate-kuadrant-auth-policy.md) for more info on generating an AuthPolicy.
+For more details, see [Generate Kuadrant AuthPolicy object from OpenAPI 3](./generate-kuadrant-auth-policy.md).
+
+#### Generate a RateLimitPolicy
 
-To generate a [RateLimitPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/) for the API, add the following `x-kuadrant` block to a path in your spec,
-replacing values to match your APIs details.
+To generate a [RateLimitPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/) for the API, add the following `x-kuadrant` block to a path in your API definition, replacing values to match your API details.
 
 ```yaml
 paths:
@@ -74,9 +79,15 @@ paths:
  unit: second
 ```
 
-When added, the UI will show this in Vendor Extensions section for that specific path:
+When added, Apicurio Studio will display the following update in the **VENDOR-EXTENSiONS** section for that specific path:
 
 ![Apicurio RateLimitPolicy Vendor Extension](./images/apicurio-vendor-extension-backend-rate-limit.png)
 
-See [this guide](./generate-kuadrant-rate-limit-policy.md) for more info on generating a RateLimitPoliicy.
-There is also the full [kuadrantctl guide](./openapi-kuadrant-extensions.md).
+For more details, see [Generate Kuadrant RateLimitPolicy object from OpenAPI 3](./generate-kuadrant-rate-limit-policy.md).
+
+## Additional resources
+
+- [OpenAPI 3.0.x Kuadrant Extensions in the kuadrantctl documentation](./openapi-kuadrant-extensions.md).
+- [Apicurio Studio - Now with OpenAPI Vendor Extensions](https://www.apicur.io/blog/2024/05/10/studio-vendor-extensions). 
+
+

doc/openapi-kuadrant-extensions.md

@@ -1,12 +1,14 @@
-## OpenAPI 3.0.X Kuadrant Extensions
+# OpenAPI 3.0.x Kuadrant extensions
 
-### Info level kuadrant extension
+This reference information shows examples of how to add Kuadrant extensions at the `info`, path, and operation level in an OpenAPI 3.0.x definition. 
 
-Kuadrant extension that can be added at the info level of the OpenAPI spec.
+## Info-level Kuadrant extension
+
+You can add a Kuadrant extension at the `info` level of an OpenAPI definition. The following example shows an extension added for a `petstore` app:
 
 ```yaml
 info:
- x-kuadrant:
+ x-kuadrant: ## Info-level Kuadrant extension
  route: ## HTTPRoute metadata
  name: "petstore"
  namespace: "petstore"
@@ -19,23 +21,23 @@ info:
  namespace: gateways
 ```
 
-### Path level kuadrant extension
+## Path-level Kuadrant extension
 
-Kuadrant extension that can be added at the path level of the OpenAPI spec.
-This configuration at the path level
-is the default when there is no operation level configuration.
+You can add a Kuadrant extension at the path level of an OpenAPI definition.
+This configuration at the path level is the default when there is no operation-level configuration. 
+The following example shows an extension added for a `/cat` path:
 
 ```yaml
 paths:
  /cat:
- x-kuadrant: ## Path level Kuadrant Extension
+ x-kuadrant: ## Path-level Kuadrant extension
  disable: true ## Remove from the HTTPRoute. Optional. Default: false
- pathMatchType: Exact ## Specifies how to match against the path Value. Valid values: [Exact;PathPrefix]. Optional. Default: Exact
+ pathMatchType: Exact ## Specifies how to match against the path value. Valid values: [Exact;PathPrefix]. Optional. Default: Exact
  backendRefs: ## Backend references to be included in the HTTPRoute. []gateway.networking.k8s.io/v1beta1.HTTPBackendRef. Optional.
  - name: petstore
  port: 80
  namespace: petstore
- rate_limit: ## Rate limit config. Optional.
+ rate_limit: ## Rate limit configuration. Optional.
  rates: ## Kuadrant API []github.com/kuadrant/kuadrant-operator/api/v1beta2.Rate
  - limit: 1
  duration: 10
@@ -48,23 +50,22 @@ paths:
  value: alice
 ```
 
-### Operation level kuadrant extension
+## Operation-level Kuadrant extension
 
-Kuadrant extension that can be added at the operation level of the OpenAPI spec.
-Same schema as path level kuadrant extension.
+You can add a Kuadrant extension at the operation level of an OpenAPI definition. This extension uses the same schema as the path-level Kuadrant extension. The following example shows an extension added for a `get` operation:
 
 ```yaml
 paths:
  /cat:
  get:
- x-kuadrant: ## Path level Kuadrant Extension
- disable: true ## Remove from the HTTPRoute. Optional. Default: path level "disable" value
- pathMatchType: Exact ## Specifies how to match against the path Value. Valid values: [Exact;PathPrefix]. Optional. Default: Exact
+ x-kuadrant: ## Operation-level Kuadrant extension
+ disable: true ## Remove from the HTTPRoute. Optional. Default: path level "disable" value.
+ pathMatchType: Exact ## Specifies how to match against the path value. Valid values: [Exact;PathPrefix]. Optional. Default: Exact.
  backendRefs: ## Backend references to be included in the HTTPRoute. Optional.
  - name: petstore
  port: 80
  namespace: petstore
- rate_limit: ## Rate limit config. Optional.
+ rate_limit: ## Rate limit configuration. Optional.
  rates: ## Kuadrant API github.com/kuadrant/kuadrant-operator/api/v1beta2.Rate
  - limit: 1
  duration: 10