CLOUDP-308422: addressing follow up comments

Author: andreaangiolillo

.github/scripts/generateSpecMapping.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Standalone specs can be added directly to the mapping. Any spec that requires displaying a version dropdown
+// will need to map its different versions to a separate Bump "branch". For example, a new resource version
+// for Atlas Admin API v2 will lead to a new entry in the array with its own Bump branch.
+const SPEC_MAPPING = [
+  {
+    doc: process.env.ATLAS_ADMIN_V1_DOC_ID,
+    file: 'openapi/v1-deprecated/v1.json',
+    branch: 'main',
+  },
+];
+
+function handleAdminAPIv2() {
+  const docId = process.env.ATLAS_ADMIN_V2_DOC_ID;
+  const directory = 'openapi/v2';
+  const filePath = path.join(__dirname, `../../${directory}/versions.json`);
+  const versions = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+
+  if (!versions || !Array.isArray(versions)) {
+    console.error(`No versions found for Atlas Admin API v2 at ${filePath}`);
+    return;
+  }
+
+  for (const [index, version] of versions.entries()) {
+    const openapiFilename = `openapi-${version}.json`;
+    const openapiFilePath = path.join(path.dirname(filePath), openapiFilename);
+
+    if (!fs.existsSync(openapiFilePath)) {
+      console.error(`Could not find resource version "${version}" at ${openapiFilePath}`);
+      continue;
+    }
+
+    const file = `${directory}/${openapiFilename}`;
+    SPEC_MAPPING.push({
+      doc: docId,
+      file,
+      branch: version,
+    });
+
+    // We want the latest version to have its own version AND be the latest/default branch
+    if (index === versions.length - 1) {
+      SPEC_MAPPING.push({
+        doc: docId,
+        file,
+        branch: 'latest',
+      });
+    }
+  }
+}
+
+handleAdminAPIv2();
+// Output to GH action
+console.log(JSON.stringify(SPEC_MAPPING));

.github/workflows/generate-bump-pages.yml

@@ -0,0 +1,78 @@
+name: Check & deploy API documentation
+
+on:
+  # For deployments
+  workflow_dispatch: # Allow manual trigger in case of quick fix
+  push:
+    branches:
+      - main
+    paths:
+      - 'openapi/**.json'
+
+  # For previews
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'openapi/**.json'
+
+permissions:
+  contents: read
+
+jobs:
+  create-matrix:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+      - name: Generate matrix
+        id: set-matrix
+        env:
+          ATLAS_ADMIN_V1_DOC_ID: ${{ vars.ATLAS_ADMIN_V1_DOC_ID }}
+          ATLAS_ADMIN_V2_DOC_ID: ${{ vars.ATLAS_ADMIN_V2_DOC_ID }}
+        run: |
+          spec_mapping=$(node .github/scripts/generateSpecMapping.js)
+          echo "matrix=$spec_mapping" >> "$GITHUB_OUTPUT"
+
+  deploy-doc:
+    needs: create-matrix
+    if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
+    name: Deploy API documentation on Bump.sh
+    strategy:
+      matrix: 
+        spec-mapping: ${{ fromJson(needs.create-matrix.outputs.matrix) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Deploy API documentation
+        uses: bump-sh/github-action@690c81156715f37cb72d006e5cbb81fbd9b45365
+        with:
+          doc: ${{matrix.spec-mapping.doc}}
+          token: ${{secrets.BUMP_TOKEN}}
+          file: ${{matrix.spec-mapping.file}}
+          branch: ${{matrix.spec-mapping.branch}}
+  
+  api-preview:
+    needs: create-matrix
+    if: ${{ github.event_name == 'pull_request' }}
+    name: Create API preview on Bump.sh
+    strategy:
+      matrix: 
+        spec-mapping: ${{ fromJSON(needs.create-matrix.outputs.matrix) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Create API preview
+        uses: bump-sh/github-action@690c81156715f37cb72d006e5cbb81fbd9b45365
+        with:
+          doc: ${{matrix.spec-mapping.doc}}
+          token: ${{secrets.BUMP_TOKEN}}
+          file: ${{matrix.spec-mapping.file}}
+          branch: ${{matrix.spec-mapping.branch}}
+          command: preview

.github/workflows/optional-spec-validations.yml

@@ -41,6 +41,7 @@ jobs:
           run-id: ${{ github.run_id }}
       - name: Run IPA validation
         id: ipa-spectral-validation
+        if: ${{ inputs.env == 'dev'}}
         run: |
           npx spectral lint openapi-foas.json --ruleset=./tools/spectral/ipa/ipa-spectral.yaml
       - name: Validate the FOAS can be used to generate Postman collection

.github/workflows/spectral-lint.yml

@@ -3,22 +3,22 @@ name: Spectral Lint Commited OpenAPI Spec
 # Trigger the workflow on pull requests and pushes to the main branch
 on:
   pull_request:
-    paths: 
+    paths:
       - 'tools/spectral/**'
       - 'openapi/**.yaml'
       - 'package.json'
   push:
     branches:
       - main
-    paths: 
+    paths:
       - 'tools/spectral/**'
       - 'openapi/**.yaml'
       - 'package.json'
 
 jobs:
   spectral-lint:
     runs-on: ubuntu-latest
-    
+
     steps:
       # Checkout the code
       - name: Checkout repository
@@ -34,6 +34,9 @@ jobs:
           cache: 'npm'
       - name: Install npm dependencies
         run: npm install
+      - name: Fetch OAS file from Dev Branch
+        run: curl -O "https://raw.githubusercontent.com/mongodb/openapi/refs/heads/dev/openapi/.raw/v2.yaml"
+        working-directory: ${{ github.workspace }}
       - name: Spectral action
         uses: stoplightio/spectral-action@2ad0b9302e32a77c1caccf474a9b2191a8060d83
         with:
@@ -43,5 +46,6 @@ jobs:
       - name: IPA validation action
         uses: stoplightio/spectral-action@2ad0b9302e32a77c1caccf474a9b2191a8060d83
         with:
-          file_glob: openapi/.raw/v2.yaml
+          file_glob: v2.yaml
           spectral_ruleset: tools/spectral/ipa/ipa-spectral.yaml
+