feat: adding sdk examples to api reference and enabling the playground (#313)

Author: pengying

.github/workflows/check-docs-config.yml

@@ -0,0 +1,26 @@
+name: Check docs config
+
+on:
+  pull_request:
+    paths:
+      - 'mintlify/docs.json'
+
+jobs:
+  check-openapi-reference:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Ensure docs.json uses production OpenAPI URL
+        run: |
+          EXPECTED_URL="https://app.stainless.com/api/spec/documented/grid/openapi.documented.yml"
+          if grep -q '"openapi.yaml"' mintlify/docs.json; then
+            echo "::error file=mintlify/docs.json::docs.json references local 'openapi.yaml' instead of the production Stainless URL."
+            echo ""
+            echo "The openapi field must point to:"
+            echo "  $EXPECTED_URL"
+            echo ""
+            echo "Local openapi.yaml is only for development (make mint handles this automatically)."
+            exit 1
+          fi
+          echo "docs.json openapi reference looks good."

Makefile

@@ -10,8 +10,14 @@ build:
 build-openapi:
 	npm run build:openapi
 
+STAINLESS_OPENAPI_URL := https://app.stainless.com/api/spec/documented/grid/openapi.documented.yml
+LOCAL_OPENAPI_PATH := openapi.yaml
+
 mint:
-	cd mintlify && mint dev
+	@cd mintlify && \
+	sed -i.bak 's|$(STAINLESS_OPENAPI_URL)|$(LOCAL_OPENAPI_PATH)|' docs.json && \
+	trap 'mv docs.json.bak docs.json' EXIT INT TERM; \
+	mint dev
 
 lint:
 	npm run lint

mintlify/docs.json

@@ -268,12 +268,23 @@
           },
           {
             "group": "API documentation",
-            "openapi": "openapi.yaml"
+            "openapi": "https://app.stainless.com/api/spec/documented/grid/openapi.documented.yml"
           }
         ]
       }
     ]
   },
+
+ "api": {
+   "playground": {
+     "display": "interactive"
+   },
+   "examples": {
+     "languages": ["curl", "javascript", "kotlin"],
+     "defaults": "all",
+     "prefill": true
+   }
+  },
   "logo": {
     "light": "/logo/light.svg",
     "dark": "/logo/dark.svg"
@@ -307,6 +318,11 @@
     "appearance": "dark"
   },
   "seo": {},
+  "integrations": {
+    "gtm": {
+      "tagId": "GTM-5R5NP3DS"
+    }
+  },
   "footer": {},
   "head": {
     "raw": "<style>@font-face{font-family:\"Suisse Intl\";src:url(\"/fonts/suisse-intl/SuisseIntl-Regular.woff2\") format(\"woff2\");font-weight:400;font-style:normal;font-display:swap;ascent-override:85%;descent-override:15%;line-gap-override:0%}@font-face{font-family:\"Suisse Intl\";src:url(\"/fonts/suisse-intl/SuisseIntl-Book.woff2\") format(\"woff2\");font-weight:450;font-style:normal;font-display:swap;ascent-override:85%;descent-override:15%;line-gap-override:0%}@font-face{font-family:\"Suisse Intl\";src:url(\"/fonts/suisse-intl/SuisseIntl-Medium.woff2\") format(\"woff2\");font-weight:500;font-style:normal;font-display:swap;ascent-override:85%;descent-override:15%;line-gap-override:0%}@font-face{font-family:\"Suisse Intl\";src:url(\"/fonts/suisse-intl/SuisseIntl-Medium.woff2\") format(\"woff2\");font-weight:700;font-style:normal;font-display:swap;ascent-override:85%;descent-override:15%;line-gap-override:0%}@font-face{font-family:\"Suisse Intl Mono\";src:url(\"/fonts/suisse-intl-mono/SuisseIntlMono-Regular-WebXL.woff2\") format(\"woff2\");font-weight:400;font-style:normal;font-display:swap}@font-face{font-family:\"Suisse Intl Mono\";src:url(\"/fonts/suisse-intl-mono/SuisseIntlMono-Bold-WebXL.woff2\") format(\"woff2\");font-weight:700;font-style:normal;font-display:swap}*{font-feature-settings:\"salt\" on}</style><style>#header:empty,#page-title:empty{display:none!important}</style><script>if(location.pathname==='/'||location.pathname==='/index'||location.pathname===''){document.write('<style>header#header,#page-title,#page-context-menu-button,#page-context-menu,.eyebrow,#pagination,[class*=\"space-y-2\"]>*{display:none!important;visibility:hidden!important;height:0!important;overflow:hidden!important;margin:0!important;padding:0!important}</style>');document.documentElement.classList.add('is-homepage');}</script><style>html.is-homepage #pagination,body.is-homepage #pagination,html.is-homepage #footer,body.is-homepage #footer,html.is-homepage header#header,body.is-homepage header#header,html.is-homepage #page-title,body.is-homepage #page-title,html.is-homepage #page-context-menu-button,body.is-homepage #page-context-menu-button,html.is-homepage #page-context-menu,body.is-homepage #page-context-menu,html.is-homepage .eyebrow,body.is-homepage .eyebrow{display:none!important;visibility:hidden!important;height:0!important;overflow:hidden!important}</style><script>if(location.pathname==='/flow-builder'){document.write('<style>header#header,#page-title,#page-context-menu-button,#page-context-menu,.eyebrow,#pagination{display:none!important;visibility:hidden!important;height:0!important;overflow:hidden!important;margin:0!important;padding:0!important}</style>');}</script><style>html:has(#flow-builder-container) header#header,html:has(#flow-builder-container) #page-title,html:has(#flow-builder-container) .eyebrow,html:has(#flow-builder-container) #page-context-menu-button,html:has(#flow-builder-container) #page-context-menu,html:has(#flow-builder-container) #pagination{display:none!important;visibility:hidden!important;height:0!important;overflow:hidden!important;margin:0!important;padding:0!important}</style>",
@@ -347,10 +363,5 @@
         "crossOrigin": "anonymous"
       }
     ]
-  },
-  "integrations": {
-    "gtm": {
-      "tagId": "GTM-5R5NP3DS"
-    }
   }
 }