feat: [FF-1612] publish combined docs for multiple applications

(monolith + astral)

.github/workflows/publish-index.yml

@@ -0,0 +1,45 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build & join docs 🏗
+        run: ./hack/build-docs.sh
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: publish
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,2 @@
+/build
+.idea

README.md

@@ -0,0 +1,36 @@
+## Ankorstore API Documentation
+This contains the centralised documentation for public APIs exposed by Ankorstore applications
+
+## Adding an API
+
+### Requirements
+* Your API spec must use version 3.1.0 of the OpenAPI Specification (OAS) to be included in this documentation.
+* Your API spec must be in YAML format to be included in this documentation.
+* Your API spec must have a x-prefix property with the name of your application
+* Your API spec must be self-contained, without references
+* You may publish multiple spec files per application, but each must individually follow the rules above
+
+### Preparing specification files
+If your API spec is composed of multiple files with $refs, please bundle them into a single file before submitting.
+```bash
+npx -y swagger-cli bundle -r -t yaml --outfile output.yaml input.yaml
+```
+
+### Publishing your API
+To publish your API spec, include the following GitHub Actions workflow:
+```yaml
+  - name: Format target folder number
+    id: format_run_number
+    run: printf 'formatted=%05d\n' "${{ github.run_number }}" >> "$GITHUB_OUTPUT"
+  - name: Publish 🚀
+    uses: JamesIves/github-pages-deploy-action@v4
+    with:
+      repository-name: ankorstore/api-docs
+      branch: main
+      folder: build
+      token: ${{ secrets.PAT }}
+      target-folder: pull/<your-app-name-here>/${{ steps.format_run_number.outputs.formatted }}
+      force: false
+```
+
+The API documentation will be updated & published automatically upon this action

hack/build-docs.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -e
+
+REDOCLY="@redocly/[email protected]"
+
+rm -rf build/redoc
+mkdir -p build/redoc
+mkdir -p publish
+
+# Function to update operationId with the prefix, as they may overlap with other specs
+update_operation_ids() {
+    local file="$1"
+    local prefix="$2"
+    local folder="$3"
+
+    # Construct the new prefix with the folder name
+    local new_prefix="${folder}-${prefix}"
+
+    # Use yq to add the new prefix to the operationId
+    yq eval '(.paths[] | .[] | select(has("operationId")) | .operationId) += "-'"$new_prefix"'"' -i "$file"
+}
+
+for projectFolder in pull/*/ ; do
+    folderName=$(basename "$projectFolder")
+
+    # Check if the folder name contains only numbers, in which case it's an old Monolith-only pull and should be skipped
+    if [[ "$folderName" =~ ^[0-9]+$ ]]; then
+        continue
+    fi
+
+    # We get the newest folder by alphabetical order, as subsequent pushes will get higher numbers
+    newestSubfolder=$(ls -d "$projectFolder"* | grep -v "^~/$" | sort | tail -n 1)
+
+    find "$newestSubfolder" -type f -name '*.yaml' | while read -r file; do
+        # Extract the x-prefix
+        prefix=$(yq eval '.info["x-prefix"]' "$file")
+
+        # Check if the x-prefix is not null, add it and fallback to application (folder) name
+        if [[ "$prefix" == "null" ]]; then
+            echo "No x-prefix found in $file"
+            echo "Falling back to folder name: $folderName"
+            prefix=folderName
+        fi
+
+        # Copy the file to the build folder, and add the prefix to avoid duplicates from across apps
+        buildFile="build/redoc/${prefix}-$(basename "$file")"
+        cp "$file" "$buildFile"
+
+        originalPrefix=$(yq eval '.info["x-prefix"]' "$file")
+
+        if [[ "$originalPrefix" == "null" ]]; then
+            yq eval ".info[\"x-prefix\"] = \"${prefix}\"" -i "$buildFile"
+        fi
+
+        update_operation_ids "$buildFile" "$prefix"
+    done
+done
+
+npx -y $REDOCLY join build/redoc/*.yaml -o build/redoc/openapi.yaml --prefix-components-with-info-prop x-prefix --prefix-tags-with-info-prop x-prefix
+
+# Set OpenAPI version and title
+yq eval '.openapi = "3.1.0"' -i build/redoc/openapi.yaml
+yq eval '.info.title = "Ankorstore APIs"' -i build/redoc/openapi.yaml
+
+spec='build/redoc/openapi.yaml'
+
+npx -y $REDOCLY build-docs -t redoc/index.hbs -o build/docs/index.html "$spec" --config redoc/redocly.yaml
+
+cp build/docs/index.html publish/index.html