From 3024658e2a2aa4b87bf54c83000641b7f21e1468 Mon Sep 17 00:00:00 2001
From: Eguzki Astiz Lezaun <eastizle@redhat.com>
Date: Mon, 13 Nov 2023 14:25:58 +0100
Subject: [PATCH] some doc

---
 doc/openapi-kuadrant-extensions.md            | 71 ++++++++++++++++++-
 .../petstore-wiht-kuadrant-extensions.yaml    | 24 +++++--
 2 files changed, 87 insertions(+), 8 deletions(-)

diff --git a/doc/openapi-kuadrant-extensions.md b/doc/openapi-kuadrant-extensions.md
index 6eabec3..594d800 100644
--- a/doc/openapi-kuadrant-extensions.md
+++ b/doc/openapi-kuadrant-extensions.md
@@ -1,3 +1,72 @@
 ## OpenAPI 3.0.X Kuadrant Extensions
 
-TODO
+### Info level kuadrant extension
+
+Kuadrant extension that can be added at the info level of the OpenAPI spec.
+
+```yaml
+info:
+  x-kuadrant:
+    route:  ## HTTPRoute metadata
+      name: "petstore"
+      namespace: "petstore"
+      hostnames:  ## []gateway.networking.k8s.io/v1beta1.Hostname
+        - example.com
+      parentRefs:  ## []gateway.networking.k8s.io/v1beta1.ParentReference
+        - name: apiGateway
+          namespace: gateways
+```
+
+### 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.
+
+```yaml
+paths:
+  /cat:
+    x-kuadrant:  ## Path level Kuadrant Extension
+      enable: true  ## Add to the HTTPRoute. Optional. Default: false
+      backendRefs:  ## Backend references to be included in the HTTPRoute. []gateway.networking.k8s.io/v1beta1.HTTPBackendRef. Optional.
+        - name: petstore
+          namespace: petstore
+      rate_limit:  ## Rate limit config. Optional.
+        rates:   ## Kuadrant API []github.com/kuadrant/kuadrant-operator/api/v1beta2.Rate
+          - limit: 1
+            duration: 10
+            unit: second
+        counters:   ## Kuadrant API []github.com/kuadrant/kuadrant-operator/api/v1beta2.CountextSelector
+          - auth.identity.username
+        when:   ## Kuadrant API []github.com/kuadrant/kuadrant-operator/api/v1beta2.WhenCondition
+          - selector: metadata.filter_metadata.envoy\.filters\.http\.ext_authz.identity.userid
+            operator: eq
+            value: alice
+```
+
+### 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.
+
+```yaml
+paths:
+  /cat:
+    get:
+      x-kuadrant:  ## Path level Kuadrant Extension
+        enable: true  ## Add to the HTTPRoute. Optional. Default: false
+        backendRefs:  ## Backend references to be included in the HTTPRoute. Optional.
+          - name: petstore
+            namespace: petstore
+        rate_limit:  ## Rate limit config. Optional.
+          rates:   ## Kuadrant API github.com/kuadrant/kuadrant-operator/api/v1beta2.Rate
+            - limit: 1
+              duration: 10
+              unit: second
+          counters:   ## Kuadrant API github.com/kuadrant/kuadrant-operator/api/v1beta2.CountextSelector
+            - auth.identity.username
+          when:   ## Kuadrant API github.com/kuadrant/kuadrant-operator/api/v1beta2.WhenCondition
+            - selector: metadata.filter_metadata.envoy\.filters\.http\.ext_authz.identity.userid
+              operator: eq
+              value: alice
+```
diff --git a/examples/oas3/petstore-wiht-kuadrant-extensions.yaml b/examples/oas3/petstore-wiht-kuadrant-extensions.yaml
index 29795a4..76a4574 100644
--- a/examples/oas3/petstore-wiht-kuadrant-extensions.yaml
+++ b/examples/oas3/petstore-wiht-kuadrant-extensions.yaml
@@ -16,7 +16,7 @@ servers:
   - url: https://example.io/v1
 paths:
   /cat:
-    x-kuadrant:
+    x-kuadrant:  ## Path level Kuadrant Extension
       enable: true
       backendRefs:
         - name: petstore
@@ -28,13 +28,13 @@ paths:
             unit: second
         counters:
           - auth.identity.username
-    get:
+    get:  # Added to the route and rate limited
       operationId: "getCat"
       responses:
         405:
           description: "invalid input"
-    post:
-      x-kuadrant:
+    post:  # NOT added to the route
+      x-kuadrant:  ## Operation level Kuadrant Extension
         enable: false
         backendRefs:
           - name: petstore
@@ -51,8 +51,8 @@ paths:
         405:
           description: "invalid input"
   /dog:
-    get:
-      x-kuadrant:
+    get:  # Added to the route and rate limited
+      x-kuadrant:  ## Operation level Kuadrant Extension
         enable: true
         backendRefs:
           - name: petstore
@@ -68,8 +68,18 @@ paths:
       responses:
         405:
           description: "invalid input"
+    post:  # Added to the route and NOT rate limited
+      x-kuadrant:  ## Operation level Kuadrant Extension
+        enable: true
+        backendRefs:
+          - name: petstore
+            namespace: petstore
+      operationId: "postDog"
+      responses:
+        405:
+          description: "invalid input"
   /mouse:
-    get:
+    get:  # NOT added to the route
       operationId: "getMouse"
       responses:
         405: