overlay: demo of applying an overlay to add x-topics

Author: paulRbr

.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^^}"

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"
+```

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.
+

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: | 

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