chore: Add build and publish OpenAPI UI workflow (#261)

# Problem

OpenAPI specs need to be published in the mono-repo.
Closes #260 

# Solution

- Updated github workflows to publish the OpenAPI spec for each service

## Steps to Verify:

1. Verify that the docs are published correctly on github pages.
2. The link tree: https://amplicalabs.github.io/gateway/
```bash
├── account
│   ├── index.html (OpenAPI spec)
├── content-watcher
│   ├── index.html (OpenAPI spec)
├── content-publishing
│   ├── index.html (OpenAPI spec)
├── graph
│   ├── index.html (OpenAPI spec)
├── index.html (mdbook)
```

.github/workflows/common/openapi-build/action.yaml

@@ -0,0 +1,43 @@
+name: Build and Publish OpenAPI UI
+description: "Build and publish OpenAPI UI for a service"
+
+inputs:
+  service:
+    description: "The name of the service to build OpenAPI UI for"
+    required: true
+    type: string
+
+runs:
+  using: "composite"
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Install Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20
+
+    - name: Install dependencies
+      run: npm ci
+      shell: bash
+      working-directory: ./services/${{ inputs.service }}
+
+    - name: Generate Swagger Metadata
+      run: npm run build:metadata
+      shell: bash
+      working-directory: ./services/${{ inputs.service }}
+
+    - name: Generate OpenAPI/Swagger JSON
+      run: npm run build:swagger
+      shell: bash
+      working-directory: ./services/${{ inputs.service }}
+
+    - name: Generate OpenAPI/Swagger UI
+      run: npm run generate-swagger-ui
+      shell: bash
+      working-directory: ./services/${{ inputs.service }}
+
+    - name: Copy OpenAPI Spec (index.html) to root docs directory
+      run: cp ./services/${{ inputs.service }}/docs/index.html ./docs/${{ inputs.service }}/
+      shell: bash

.github/workflows/deploy-gh-pages.yaml

@@ -15,7 +15,8 @@ permissions:
   id-token: write
 
 jobs:
-  build:
+  # Build mdbook
+  build-mdbook: 
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -33,19 +34,89 @@ jobs:
         working-directory: docs
         run: mdbook build && ls book
 
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+      # Upload the mdBook output to GitHub Pages
+      - name: Upload mdbook to GitHub Pages
+        uses: actions/upload-artifact@v4
         with:
-          path: ./docs/book
+          name: mdbook
+          path: ./docs
+
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        service:
+          - account
+          - content-watcher
+          - content-publishing
+          - graph
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Publish OpenAPI specs for each microservice
+      - name: Build and Publish OpenAPI spec for ${{ matrix.service }}
+        uses: ./.github/workflows/common/openapi-build
+        with:
+          service: ${{ matrix.service }}
+
+      - name: Upload OpenAPI UI artifact for ${{ matrix.service }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-${{ matrix.service }}
+          path: ./docs/${{ matrix.service }}
 
   # Deployment job
   deploy:
+    name: Deploy mdbook and OpenAPI microservices to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: [build, build-mdbook]
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
     steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download mdbook artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: mdbook
+          path: ./docs
+
+      - name: Move mdbook to root
+        run: mv ./docs/book/* ./docs
+        shell: bash
+
+      - name: Download account OpenAPI artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: openapi-account
+          path: ./docs/account
+
+      - name: Download content-watcher OpenAPI artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: openapi-content-watcher
+          path: ./docs/content-watcher
+
+      - name: Download content-publishing OpenAPI artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: openapi-content-publishing
+          path: ./docs/content-publishing
+
+      - name: Download graph OpenAPI artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: openapi-graph
+          path: ./docs/graph
+
+      - name: Upload final result to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

services/content-publishing/package.json

@@ -5,9 +5,9 @@
   "main": "dist/apps/api/main.js",
   "scripts": {
     "build": "nest build api && nest build worker",
-    "build:swagger": "npx ts-node -r tsconfig-paths/register apps/api/src/build-openapi.ts",
-    "build:metadata": "npx ts-node apps/api/src/generate-metadata.ts",
-    "generate-swagger-ui": "npx --yes @redocly/cli build-docs swagger.json --output=./docs/index.html",
+    "build:swagger": "set -a ; . ./env.template ; npx ts-node -r tsconfig-paths/register apps/api/src/build-openapi.ts",
+    "build:metadata": "set -a ; . ./env.template ; npx ts-node apps/api/src/generate-metadata.ts",
+    "generate-swagger-ui": "set -a ; . ./env.template ; npx --yes @redocly/cli build-docs swagger.json --output=./docs/index.html",
     "format": "prettier --write \"apps/**/*.ts\" \"libs/**/*.ts\"",
     "start:api": "nest start api",
     "start:api:watch": "nest start api --watch",

services/content-watcher/package.json

@@ -10,9 +10,9 @@
     "start:dev": "set -a ; . .env ; nest start api --watch",
     "start:debug": "set -a ; . .env ; nest start api --debug --watch",
     "build": "nest build",
-    "build:swagger": "npx ts-node -r tsconfig-paths/register apps/api/src/build-openapi.ts",
-    "build:metadata": "npx ts-node apps/api/src/generate-metadata.ts",
-    "generate-swagger-ui": "npx --yes @redocly/cli build-docs swagger.json --output=./docs/index.html",
+    "build:swagger": "set -a ; . ./env.template ; npx ts-node -r tsconfig-paths/register apps/api/src/build-openapi.ts",
+    "build:metadata": "set -a ; . ./env.template ; npx ts-node apps/api/src/generate-metadata.ts",
+    "generate-swagger-ui": "set -a ; . ./env.template ; npx --yes @redocly/cli build-docs swagger.json --output=./docs/index.html",
     "format": "prettier --write \"apps/**/*.ts\" \"libs/**/*.ts\"",
     "docker-build": "docker build -t content-watcher-service .",
     "docker-build:dev": "docker-compose build",

services/graph/package.json

@@ -5,9 +5,9 @@
   "main": "dist/apps/api/main.js",
   "scripts": {
     "build": "nest build api && nest build worker",
-    "build:swagger": "npx ts-node -r tsconfig-paths/register apps/api/src/build-openapi.ts",
-    "build:metadata": "npx ts-node apps/api/src/generate-metadata.ts",
-    "generate-swagger-ui": "npx --yes @redocly/cli build-docs swagger.json --output=./docs/index.html",
+    "build:swagger": "set -a ; . ./env.template ; npx ts-node -r tsconfig-paths/register apps/api/src/build-openapi.ts",
+    "build:metadata": "set -a ; . ./env.template ; npx ts-node apps/api/src/generate-metadata.ts",
+    "generate-swagger-ui": "set -a ; . ./env.template ; npx --yes @redocly/cli build-docs swagger.json --output=./docs/index.html",
     "generate-webhook-types": "npx openapi-client-axios-typegen graph-webhooks.openapi.yaml > libs/common/src/types/webhook-types.d.ts",
     "start:api": "nest start api",
     "start:api:watch": "nest start api --watch",