interledger · melissahenderson · Jul 16, 2025 · Jul 9, 2025 · Jul 9, 2025 · Jul 9, 2025
diff --git a/packages/documentation/astro.config.mjs b/packages/documentation/astro.config.mjs
@@ -3,7 +3,6 @@ import starlight from '@astrojs/starlight'
 
 import remarkMath from 'remark-math'
 import rehypeMathjax from 'rehype-mathjax'
-import GraphQL from 'astro-graphql-plugin'
 import starlightLinksValidator from 'starlight-links-validator'
 import starlightFullViewMode from 'starlight-fullview-mode'
 import { rehypeHeadingIds } from '@astrojs/markdown-remark'
@@ -308,16 +307,20 @@ export default defineConfig({
             },
             {
               label: 'Backend Admin API',
-              collapsed: true,
-              autogenerate: {
-                directory: 'apis/graphql/backend'
+              link: '/apis/graphql/backend',
+              attrs: {
+                target: '_blank',
+                rel: 'noopener noreferrer',
+                'data-icon': 'external'
               }
             },
             {
               label: 'Auth Admin API',
-              collapsed: true,
-              autogenerate: {
-                directory: 'apis/graphql/auth'
+              link: '/apis/graphql/auth',
+              attrs: {
+                target: '_blank',
+                rel: 'noopener noreferrer',
+                'data-icon': 'external'
               }
             }
           ]
@@ -355,21 +358,18 @@ export default defineConfig({
       ],
       plugins: [
         starlightLinksValidator({
+          exclude: [
+            '/apis/graphql/auth',
+            '/apis/graphql/backend',
+            '/apis/graphql/auth/*',
+            '/apis/graphql/backend/*'
+          ],
           errorOnLocalLinks: false,
-          errorOnFallbackPages: false
+          errorOnFallbackPages: false,
+          errorOnInvalidHashes: false
         }),
         starlightFullViewMode()
       ]
-    }),
-    GraphQL({
-      schema: '../backend/src/graphql/schema.graphql',
-      output: './src/content/docs/apis/graphql/backend/',
-      linkPrefix: '/apis/graphql/backend/'
-    }),
-    GraphQL({
-      schema: '../auth/src/graphql/schema.graphql',
-      output: './src/content/docs/apis/graphql/auth/',
-      linkPrefix: '/apis/graphql/auth/'
     })
   ],
   server: {

diff --git a/packages/documentation/config-auth.yml b/packages/documentation/config-auth.yml
@@ -0,0 +1,31 @@
+spectaql:
+  oneFile: true
+  targetDir: ./src/pages/apis/graphql/auth
+  logoFile: ./public/img/logo.png
+  embedLogo: true
+  faviconUrl: /favicon.svg
+  displayAllServers: true
+
+introspection:
+  removeTrailingPeriodFromDescriptions: false
+  schemaFile: '../auth/src/graphql/schema.graphql'
+  queryNameStrategy: capitalizeFirst
+  fieldExpansionDepth: 2
+
+  spectaqlDirective:
+    enable: true
+
+extensions:
+  graphqlScalarExamples: true
+
+info:
+  title: Auth Admin API
+  description: The Auth Admin API allows you to get information about a grant, such as its status, state, related payment details, and the wallet address of the grantee’s account. The API also allows you to revoke grants.
+  x-introItems:
+    - title: Back to documentation
+      url: /overview/overview
+  x-hidePoweredBy: true
+
+servers:
+  - url: https://staging.example.com/graphql
+    description: Staging
diff --git a/packages/documentation/config-backend.yml b/packages/documentation/config-backend.yml
@@ -0,0 +1,31 @@
+spectaql:
+  oneFile: true
+  targetDir: ./src/pages/apis/graphql/backend
+  logoFile: ./public/img/logo.png
+  embedLogo: true
+  faviconUrl: /favicon.svg
+  displayAllServers: true
+
+introspection:
+  removeTrailingPeriodFromDescriptions: false
+  schemaFile: '../backend/src/graphql/schema.graphql'
+  queryNameStrategy: capitalizeFirst
+  fieldExpansionDepth: 2
+
+  spectaqlDirective:
+    enable: true
+
+extensions:
+  graphqlScalarExamples: true
+
+info:
+  title: Backend Admin API
+  description: The Backend Admin API provides you with comprehensive capabilities to manage your Rafiki instance. Core functionality includes managing peering relationships, assets, wallet addresses and their public keys, as well as liquidity management through deposits and withdrawals. Another important aspect of the Backend Admin API is to manage Open Payments resources like payments and quotes.
+  x-introItems:
+    - title: Back to documentation
+      url: /overview/overview
+  x-hidePoweredBy: true
+
+servers:
+  - url: https://staging.example.com/graphql
+    description: Staging
diff --git a/packages/documentation/package.json b/packages/documentation/package.json
@@ -13,12 +13,11 @@
     "@astrojs/starlight": "^0.34.4",
     "@interledger/docs-design-system": "^0.8.0",
     "astro": "5.11.0",
-    "astro-graphql-plugin": "^0.4.2",
-    "graphql": "16.11.0",
     "mermaid": "^11.8.1",
     "rehype-autolink-headings": "^7.1.0",
     "rehype-mathjax": "^7.1.0",
     "remark-math": "^6.0.0",
+    "spectaql": "^3.0.4",
     "starlight-fullview-mode": "^0.2.3",
     "starlight-links-validator": "^0.17.0"
   }

diff --git a/packages/documentation/public/img/logo.png b/packages/documentation/public/img/logo.png
diff --git a/packages/documentation/src/content/docs/es/index.mdx b/packages/documentation/src/content/docs/es/index.mdx
@@ -27,12 +27,12 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'
       Review the requirements for deploying Rafiki to a production environment.
     </Card>
   </a>
-  <a class='card-link' href='/apis/graphql/backend/mutations/'>
+  <a class='card-link' href='/apis/graphql/backend'>
     <Card title='View Backend API schema' icon='document'>
       Discover what's in our Backend GraphQL schema.
     </Card>
   </a>
-  <a class='card-link' href='/apis/graphql/auth/mutations/'>
+  <a class='card-link' href='/apis/graphql/auth'>
     <Card title='View Auth API schema' icon='document'>
       Discover what's in our Auth GraphQL schema.
     </Card>

diff --git a/packages/documentation/src/content/docs/index.mdx b/packages/documentation/src/content/docs/index.mdx
@@ -27,12 +27,12 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'
       Review the requirements for deploying Rafiki to a production environment.
     </Card>
   </a>
-  <a class='card-link' href='/apis/graphql/backend/mutations/'>
+  <a class='card-link' href='/apis/graphql/backend'>
     <Card title='View Backend API schema' icon='document'>
       Discover what's in our Backend GraphQL schema.
     </Card>
   </a>
-  <a class='card-link' href='/apis/graphql/auth/mutations/'>
+  <a class='card-link' href='/apis/graphql/auth'>
     <Card title='View Auth API schema' icon='document'>
       Discover what's in our Auth GraphQL schema.
     </Card>

diff --git a/packages/documentation/src/content/docs/integration/deployment/helm-k8s.mdx b/packages/documentation/src/content/docs/integration/deployment/helm-k8s.mdx
@@ -24,8 +24,8 @@ We recommended using the latest vendor supported version for each of the softwar
 Before you begin, ensure you have the following:
 
 - <LinkOut href='https://kubernetes.io/'>Kubernetes</LinkOut> cluster deployed
-- <LinkOut href='https://kubernetes.io/docs/tasks/tools/'>kubectl</LinkOut> installed
-  and configured
+- <LinkOut href='https://kubernetes.io/docs/tasks/tools/'>kubectl</LinkOut>
+  installed and configured
 - <LinkOut href='https://helm.sh/docs/intro/install/'>Helm</LinkOut> installed
 
 ## Install Rafiki using Helm

diff --git a/packages/documentation/src/content/docs/integration/requirements/assets.mdx b/packages/documentation/src/content/docs/integration/requirements/assets.mdx
@@ -38,7 +38,7 @@ An asset represents an item of value that can be transferred via the Interledger
       }
     }
     ```
-    For more information about this mutation's input object, see [`CreateAssetInput`](/apis/graphql/backend/inputobjects/#createassetinput).
+    For more information about this mutation's input object, see [`CreateAssetInput`](/apis/graphql/backend/#definition-CreateAssetInput).
   </TabItem>
   <TabItem label="Response">
     ```json

diff --git a/...ion/src/content/docs/integration/requirements/open-payments/grants-revoking.mdx b/...ion/src/content/docs/integration/requirements/open-payments/grants-revoking.mdx
@@ -88,7 +88,7 @@ query Grants(
 }
 }
 ```
-For more information about this query's variables, see [`grants`](/apis/graphql/auth/queries/#grants).
+For more information about this query's variables, see [`grants`](/apis/graphql/auth/#query-grants).
 </TabItem>
 
 <TabItem label='Response'>
@@ -170,7 +170,7 @@ mutation revokeGrant($input: RevokeGrantInput!) {
     }
 }
 ```
-For more information about this mutation's input object, see [`RevokeGrantInput`](/apis/graphql/auth/inputobjects/#revokegrantinput).
+For more information about this mutation's input object, see [`RevokeGrantInput`](/apis/graphql/auth/#definition-RevokeGrantInput).
 </TabItem>
 
 <TabItem label='Response'>

diff --git a/packages/documentation/src/content/docs/integration/requirements/peers.mdx b/packages/documentation/src/content/docs/integration/requirements/peers.mdx
@@ -106,7 +106,7 @@ As mentioned in the prerequisites, you must add an asset to your Rafiki instance
       }
     }
     ```
-    For more information about this mutation's input object, see [`CreatePeerInput`](/apis/graphql/backend/inputobjects/#createpeerinput).
+    For more information about this mutation's input object, see [`CreatePeerInput`](/apis/graphql/backend/#definition-CreatePeerInput).
   </TabItem>
   <TabItem label="Response">
     ```json
@@ -174,7 +174,7 @@ In this example we will update the peer we just created. Rather than change any
       }
     }
     ```
-    For more information about this mutation's input object, see [`UpdatePeerInput`](/apis/graphql/backend/inputobjects/#updatepeerinput).
+    For more information about this mutation's input object, see [`UpdatePeerInput`](/apis/graphql/backend/#definition-UpdatePeerInput).
   </TabItem>
   <TabItem label="Response">
     ```json
@@ -233,7 +233,7 @@ Deleting a peer is permanent and cannot be reversed. If you delete a peer in err
       }
     }
     ```
-    For more information about this mutation's input object, see [`DeletePeerInput`](/apis/graphql/backend/inputobjects/#deletepeerinput).
+    For more information about this mutation's input object, see [`DeletePeerInput`](/apis/graphql/backend/#definition-DeletePeerInput).
   </TabItem>
   <TabItem label="Response">
     ```json

diff --git a/packages/documentation/src/content/docs/integration/requirements/sending-fees.mdx b/packages/documentation/src/content/docs/integration/requirements/sending-fees.mdx
@@ -46,7 +46,7 @@ You have the option to charge sending fees, on top of any estimated network fees
       }
     }
     ```
-    For more information about this mutation's input object, see [`SetFeeInput`](/apis/graphql/backend/inputobjects/#setfeeinput).
+    For more information about this mutation's input object, see [`SetFeeInput`](/apis/graphql/backend/#definition-SetFeeInput).
   </TabItem>
   <TabItem label="Response">
     ```json

diff --git a/...es/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx b/...es/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx
@@ -77,7 +77,7 @@ Ensure your script calls the `createWalletAddress` GraphQL mutation.
       }
     }
     ```
-    For more information about this mutation's input object, see [`CreateWalletAddressInput`](/apis/graphql/backend/inputobjects/#createwalletaddressinput).
+    For more information about this mutation's input object, see [`CreateWalletAddressInput`](/apis/graphql/backend/#definition-CreateWalletAddressInput).
   </TabItem>
   <TabItem label="Response">
     ```json