Generated API references from OpenAPI file

.code-samples.meilisearch.yaml

@@ -2,7 +2,7 @@
 # Every example written here will be automatically fetched by
 # the documentation on build
 ---
-## BEGIN /references/api
+## BEGIN /reference/api
 # get_indexes_indexUid
 get_one_index_1: |-
   curl \
@@ -850,7 +850,7 @@ get_health_1: |-
 get_version_1: |-
   curl \
     -X GET 'MEILISEARCH_URL/version'
-## END /references/api
+## END /reference/api
 
 distinct_attribute_guide_1: |-
   curl \
@@ -1579,3 +1579,8 @@ multi_search_remote_federated_1: |-
           }
         }
       ]
+# post_indexes_indexUid_fields
+list_index_fields_1: |-
+  curl \
+    -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/fields' \
+    -H 'Content-Type: application/json'

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Description
+
+<!-- Describe the changes and purpose of the PR -->
+
+## Checklist
+
+For internal Meilisearch team member only:
+- [ ] I checked and followed our [internal guidelines](https://www.notion.so/meilisearch/Updating-docs-for-engineers-3034b06b651f808da3c6c4f5e34914fc?source=copy_link)
+- [ ] ⚠️ I updated the code samples according to our [internal guidelines](https://www.notion.so/meilisearch/Updating-docs-for-engineers-3034b06b651f808da3c6c4f5e34914fc?source=copy_link#3034b06b651f8026bd63cfa294dfa0c6)
+
+For external maintainers
+- [ ] Did you use any AI tool while implementing this PR (code, tests, docs, etc.)? If yes, disclose it in the PR description and describe what it was used for. AI usage is allowed when it is disclosed.
+- [ ] Have you made sure that the title is accurate and descriptive of the changes?

.github/workflows/docs-sdk-code-samples-check.yml

@@ -1,7 +1,7 @@
 # Runs daily and on workflow_dispatch.
 # - Job 1: Fails if local code samples are not properly used (route comment → OpenAPI, no comment → snippet in docs).
 # - Job 2: Fails if any SDK has code samples not present in the local .code-samples.meilisearch.yaml.
-# - Job 3: Informational only (never fails) – lists local samples missing from each SDK.
+# - Job 3: Informational only (never fails) – lists CodeSamples* import keys missing from each SDK.
 name: Check Docs & SDK code sample files
 
 on:
@@ -20,7 +20,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Check local code samples are used
-        run: node scripts/check-code-samples-usage.mjs
+        run: npm run check-code-samples-usage
 
   # Fails if an SDK's .code-samples.meilisearch.yaml contains keys absent from
   # the local .code-samples.meilisearch.yaml (those SDK samples are useless).
@@ -30,22 +30,32 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
       - name: Install dependencies
-        run: npm ci
+        run: npm install
 
       - name: Check for unused SDK code samples
-        run: node scripts/check-unused-sdk-samples.mjs
+        run: npm run check-unused-sdk-samples
 
   # Informational only – this job never fails.
-  # Lists local samples that are missing from each SDK.
+  # Lists code sample keys referenced by CodeSamples* imports in the docs that are missing from each SDK.
   missing-sdk-samples:
     name: "[Info only - never fails] Missing SDK code samples"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
       - name: Install dependencies
-        run: npm ci
+        run: npm install
 
       - name: List missing SDK code samples (informational, never fails)
-        run: node scripts/check-missing-sdk-samples.mjs
+        run: npm run check-missing-sdk-samples

.github/workflows/openapi-code-samples-check.yml

@@ -0,0 +1,50 @@
+# On every push to main, check meilisearch-openapi-mintlify.json for code samples:
+# - Job 1: Ensure every route that has x-codeSamples includes a cURL sample (can fail).
+# - Job 2: Informational only – list routes and all missing code sample languages (never fails).
+name: OpenAPI code samples check
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  # Fails if any route with x-codeSamples has no cURL sample.
+  require-curl-samples:
+    name: Require cURL in x-codeSamples
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Check routes have cURL in x-codeSamples
+        run: |
+          npm run check-openapi-code-samples -- curl-check assets/open-api/meilisearch-openapi-mintlify.json
+
+  # Informational only: list routes and missing code sample languages.
+  # This job never fails the workflow (information check only).
+  info-missing-code-samples:
+    name: "[Info only - never fails] Missing code samples per route"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: List routes and missing code samples (informational, never fails)
+        run: |
+          npm run check-openapi-code-samples -- info assets/open-api/meilisearch-openapi-mintlify.json || true

.github/workflows/post-deployment.yml

@@ -4,45 +4,168 @@ name: Post Deployment
 
 on:
   workflow_dispatch:
-  # schedule:
-  #   - cron: '0 23 * * *' # Every day at 11:00 PM UTC
-  # push:
-  #   branches:
-  #     - 'main'
+  schedule:
+    - cron: '0 23 * * *' # Every day at 11:00 PM UTC
+  push:
+    branches:
+      - 'main'
+
+concurrency:
+  group: post-deployment
+  cancel-in-progress: false
 
 jobs:
-  update-samples:
+  build-code-samples:
+    name: Build code samples
     runs-on: ubuntu-latest
+    outputs:
+      run_openapi_automation: ${{ steps.openapi_automation.outputs.run }}
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
         with:
           token: ${{ secrets.GH_TOKEN }}
 
+      - name: Get OpenAPI automation flag from docs.json
+        id: openapi_automation
+        run: |
+          value=$(jq -r '.. | select(type == "object" and has("internal-meili-fetch-automation")) | .["internal-meili-fetch-automation"] | select(. != null) | tostring' docs.json 2>/dev/null | head -1)
+          echo "run=${value:-false}" >> "$GITHUB_OUTPUT"
+
       - name: Setup Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
 
       - name: Install dependencies
         run: npm install
 
       - name: Generate code sample snippets
-        run: node scripts/generate-code-sample-snippets.mjs
+        run: npm run generate-code-sample-snippets-file
 
       - name: Check for changes
         id: changes
         run: |
-          echo "has_changes=$(git diff --quiet snippets/ && echo "false" || echo "true")" >> "$GITHUB_ENV"
+          if git diff --quiet snippets/; then
+            echo "has_changes=false" >> "$GITHUB_ENV"
+          else
+            echo "has_changes=true" >> "$GITHUB_ENV"
+          fi
 
       - name: Commit changes
         run: |
           if [[ $has_changes == "true" ]]; then
             echo "There are changes in the Git working directory."
             git config user.name "meili-bot"
-            git config user.email "meili-bot@meilisearch.com"
+            git config user.email "robot@meilisearch.com"
             git add snippets/
-            git commit -m "Update code samples"
+            git commit -m "[AUTOMATION POST DEPLOYMENT] Update code samples"
             git push origin main
           else
             echo "No changes in the Git working directory."
           fi
+
+  # We need to wait for build-code-samples to commit first so we can push a separate commit
+  # (avoid stacking both changes in one run and keep history clear).
+  # Only runs when docs.json has "internal-meili-fetch-automation": true.
+  # In case of issues with the latest release OpenAPI file: fetch the desired OpenAPI file
+  # manually, then set "internal-meili-fetch-automation" to false to prevent this automation from running.
+  fetch-openapi-file:
+    name: Fetch OpenAPI file from Meilisearch release
+    runs-on: ubuntu-latest
+    needs: build-code-samples
+    if: needs.build-code-samples.outputs.run_openapi_automation == 'true'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: main
+          token: ${{ secrets.GH_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Fetch latest meilisearch-openapi.json from Meilisearch release
+        run: npm run fetch-meilisearch-openapi-file
+
+      - name: Check for changes
+        id: openapi_changes
+        run: |
+          if git diff --quiet assets/open-api/meilisearch-openapi.json; then
+            echo "has_changes=false" >> "$GITHUB_ENV"
+          else
+            echo "has_changes=true" >> "$GITHUB_ENV"
+          fi
+
+      - name: Commit changes
+        run: |
+          if [[ $has_changes == "true" ]]; then
+            echo "There are changes in the OpenAPI file."
+            git config user.name "meili-bot"
+            git config user.email "robot@meilisearch.com"
+            git add assets/open-api/meilisearch-openapi.json
+            git commit -m "[AUTOMATION POST DEPLOYMENT] Update meilisearch-openapi.json from latest Meilisearch release"
+            git push origin main
+          else
+            echo "No changes in the OpenAPI file."
+          fi
+
+  # Runs after fetch-openapi-file: generate Mintlify OpenAPI file, validate with mint openapi-check, commit if valid.
+  generate-and-check-mintlify-openapi:
+    name: Generate and check Mintlify OpenAPI file
+    runs-on: ubuntu-latest
+    needs: [build-code-samples, fetch-openapi-file]
+    if: needs.build-code-samples.outputs.run_openapi_automation == 'true'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: main
+          token: ${{ secrets.GH_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Generate Mintlify OpenAPI file
+        run: npm run generate-mintlify-openapi-file
+
+      - name: Validate OpenAPI with Mintlify CLI
+        run: npx mint openapi-check assets/open-api/meilisearch-openapi-mintlify.json
+
+      - name: Check for changes
+        id: mintlify_changes
+        run: |
+          if git diff --quiet assets/open-api/meilisearch-openapi-mintlify.json; then
+            echo "has_changes=false" >> "$GITHUB_ENV"
+          else
+            echo "has_changes=true" >> "$GITHUB_ENV"
+          fi
+
+      - name: Commit changes
+        run: |
+          if [[ $has_changes == "true" ]]; then
+            echo "There are changes in the Mintlify OpenAPI file."
+            git config user.name "meili-bot"
+            git config user.email "robot@meilisearch.com"
+            git add assets/open-api/meilisearch-openapi-mintlify.json
+            git commit -m "[AUTOMATION POST DEPLOYMENT] Update meilisearch-openapi-mintlify.json"
+            git push origin main
+          else
+            echo "No changes in the Mintlify OpenAPI file."
+          fi