From 7eb2f70a94ca9bf0a62a65718ccbeeda0a74362e Mon Sep 17 00:00:00 2001
From: Abdallah Abedraba <aabedraba@gmail.com>
Date: Tue, 29 Nov 2022 15:13:13 +0100
Subject: [PATCH] create overlays docs (#990)

---
 docs/docs/guides/overlays.md | 107 +++++++++++++++++++++++++++++++++++
 docs/sidebars.js             |   1 +
 2 files changed, 108 insertions(+)
 create mode 100644 docs/docs/guides/overlays.md

diff --git a/docs/docs/guides/overlays.md b/docs/docs/guides/overlays.md
new file mode 100644
index 000000000..fc72529e6
--- /dev/null
+++ b/docs/docs/guides/overlays.md
@@ -0,0 +1,107 @@
+# OpenAPI Overlays
+
+Kusk supports code-first approaches, i.e. OpenAPI generated from code annotations, by use of OpenAPI Overlays.
+
+[OpenAPI Overlays](https://github.com/OAI/Overlay-Specification) is a new specification that allows you to have an OpenAPI file without any Kusk extensions, and an overlay file containing the extenions you would want to add to your OpenAPI definition. 
+
+After merging the overlay with the OpenAPI file, the resulting file is an OpenAPI definition with all the metadata added to it, ready to be deployed by Kusk.
+
+This way, teams can generate their OpenAPI from code, and then add the gateway deployment metadata later.
+
+## Example
+
+Let's start with an OpenAPI definition that does not have any Kusk extensions added to it.
+
+```yaml file="openapi.yaml"
+openapi: 3.0.0
+servers:
+  - url: http://api.mydomain.com
+info:
+  title: simple-api
+  version: 0.1.0
+paths:
+  /hello:
+    get:
+      summary: Returns a Hello world to the user
+      responses:
+        '200':
+          description: A simple hello world!
+          content:
+            application/json; charset=utf-8:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                required:
+                  - message
+```
+
+Now let's create an overlay that adds Kusk mocking policy to our OpenAPI definition. 
+
+```yaml file="overlay.yaml" 
+overlays: 1.0.0
+extends: ./openapi.yaml
+actions:
+  - target: "$"
+    update:
+      mocking:
+        enabled: true
+```
+
+To apply the overlay to the OpenAPI definition, run: 
+
+```sh 
+kusk deploy --overlay overlay.yaml
+```
+
+```sh title="Expected output"
+🎉 successfully parsed
+✅ initiallizing deployment to fleet kusk-gateway-envoy-fleet
+api.gateway.kusk.io/simple-api created
+```
+
+If you want to look at the generated OpenAPI file before deploying it to Kusk, you can run: 
+
+```sh 
+kusk generate --overlay overlay.yaml
+```
+
+```yaml title="Expected output"
+apiVersion: gateway.kusk.io/v1alpha1
+kind: API
+metadata:
+  name: simple-api
+  namespace: default
+spec:
+  fleet:
+    name: kusk-gateway-envoy-fleet
+    namespace: kusk-system
+  spec: |
+    openapi: 3.0.0
+    servers:
+    - url: http://api.mydomain.com
+    components: {}
+    info:
+      title: simple-api
+      version: 0.1.0
+    x-kusk:
+      mocking:
+        enabled: true
+    paths:
+      /hello:
+        get:
+          responses:
+            "200":
+              content:
+                application/json; charset=utf-8:
+                  schema:
+                    properties:
+                      message:
+                        type: string
+                    required:
+                    - message
+                    type: object
+              description: A simple hello world!
+          summary: Returns a Hello world to the user
+```
\ No newline at end of file
diff --git a/docs/sidebars.js b/docs/sidebars.js
index be33caef5..d9bafbeee 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -70,6 +70,7 @@ const sidebars = {
         "guides/timeouts",
         "guides/routing",
         "guides/rate-limit",
+        "guides/overlays",
         "guides/cert-manager",
         "guides/troubleshooting",
         "guides/observability",