From 86a9bc0b4b39e30df6cfa058396bc086721c5253 Mon Sep 17 00:00:00 2001
From: "Paul B." <paulr@bump.sh>
Date: Thu, 12 Jun 2025 07:52:02 +0200
Subject: [PATCH] overlay: demo of applying an overlay to add x-topics

---
 .github/scripts/deploy-all.sh                    | 10 ++++++++++
 .../docs/authentication/example.md               | 15 +++++++++++++++
 .../docs/authentication/index.md                 | 11 +++++++++++
 .../trainbook-openapi-source.yaml                |  5 -----
 hubs/my-train-company/trainbook-overlay.yml      | 16 ++++++++++++++++
 5 files changed, 52 insertions(+), 5 deletions(-)
 create mode 100644 hubs/my-train-company/docs/authentication/example.md
 create mode 100644 hubs/my-train-company/docs/authentication/index.md
 create mode 100644 hubs/my-train-company/trainbook-overlay.yml

diff --git a/.github/scripts/deploy-all.sh b/.github/scripts/deploy-all.sh
index ea0dbe6..dd04dca 100755
--- a/.github/scripts/deploy-all.sh
+++ b/.github/scripts/deploy-all.sh
@@ -11,6 +11,7 @@ npm install -g bump-cli
 # For each directory in the hubs/ directory
 for hub in hubs/*/; do
     for api in "${hub}"*-source.{yml,yaml,json}; do
+        [ -f "${api}" ] || continue
         # Extract the Hub name from directory structure
         hubName="${hub%/*}"
         hubName="${hubName#*/}"
@@ -21,6 +22,15 @@ for hub in hubs/*/; do
         apiName="${apiName#*/}"
         apiName="${apiName#*/}"
 
+        # Apply any available overlays from filename
+        # `<api_name>-overlay*.yaml`
+        for overlay in "${hub}"/"${apiName}"-overlay*.{yml,yaml}; do
+            [ -f "${overlay}" ] || continue
+            # Overide current api definition file with overlayed
+            # definition
+            yes | npx bump-cli overlay "${api}" "${overlay}" -o "${api}"
+        done
+
         # Create documentation <apiName> from the api definition file
         tokenKey="${hubName//-/_}_BUMP_TOKEN"
         tokenKey="${tokenKey^^}"
diff --git a/hubs/my-train-company/docs/authentication/example.md b/hubs/my-train-company/docs/authentication/example.md
new file mode 100644
index 0000000..71e2bd9
--- /dev/null
+++ b/hubs/my-train-company/docs/authentication/example.md
@@ -0,0 +1,15 @@
+#    
+
+```
+curl \
+  -X GET https://bump.sh/api/v1/versions/1 \
+  -H "Authorization: Token $ACCESS_TOKEN"
+```
+
+#    
+
+```
+curl \
+  -X GET https://bump.sh/api/v1/versions/1 \
+  -u ":$ACCESS_TOKEN"
+```
diff --git a/hubs/my-train-company/docs/authentication/index.md b/hubs/my-train-company/docs/authentication/index.md
new file mode 100644
index 0000000..6093fa4
--- /dev/null
+++ b/hubs/my-train-company/docs/authentication/index.md
@@ -0,0 +1,11 @@
+# Http token authentication
+
+> success
+> This is the preferred authentication method for restricted access API endpoints
+
+Use the token from your documentation settings in the HTTP token authorization header.
+
+# Basic authentication
+
+*(Deprecated)* Use the token from your documentation settings as the username of the basic auth, with no password.
+
diff --git a/hubs/my-train-company/trainbook-openapi-source.yaml b/hubs/my-train-company/trainbook-openapi-source.yaml
index c3973a6..f9b4d3c 100644
--- a/hubs/my-train-company/trainbook-openapi-source.yaml
+++ b/hubs/my-train-company/trainbook-openapi-source.yaml
@@ -31,11 +31,6 @@ security:
   - OAuth2:
       - read
 
-x-topics:
-  - title: Getting started
-    content:
-      $ref: ./docs/getting-started.md
-
 tags:
   - name: Stations
     description: | 
diff --git a/hubs/my-train-company/trainbook-overlay.yml b/hubs/my-train-company/trainbook-overlay.yml
new file mode 100644
index 0000000..6624d50
--- /dev/null
+++ b/hubs/my-train-company/trainbook-overlay.yml
@@ -0,0 +1,16 @@
+overlay: 1.0.0
+info:
+  title: Add all the x-topics files as references
+  version: 0.0.1
+actions:
+  - target: '$'
+    update:
+      x-topics:
+        - title: Getting started
+          content:
+            $ref: ./docs/getting-started.md
+        - title: Authentication
+          content:
+            $ref: ./docs/authentication/index.md
+          example:
+            $ref: ./docs/authentication/example.md