add spectaql docs

.github/workflows/docs.yaml

@@ -2,9 +2,9 @@ name: Build and deploy the documentation
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, test_spectaql ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, test_spectaql ]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -43,6 +43,9 @@ jobs:
       - name: Build the documentation
         run: sh misc/build-docs.sh
 
+      - name: Build the spectaql
+        run: sh misc/build-spectaql.sh
+
       - name: Fix permissions
         run: |
           chmod -c -R +rX "target/book/" | while read line; do

docs/README.md

@@ -9,3 +9,4 @@ A hosted version is available at <https://matrix-org.github.io/matrix-authentica
 
  - Technical documentation for individual crates: [`rustdoc`](./rustdoc/mas_handlers/)
  - UI components: [`storybook`](./storybook/)
+ - GraphQL: [`storybook`](./spectaql/)

misc/build-spectaql.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+set -eux
+
+# Sanity check
+npx --version
+
+npm install spectaql
+
+npx spectaql ./spectaql/config.yml

spectaql/config.yml

@@ -0,0 +1,43 @@
+spectaql:
+  # logoFile: ./spectaql/logo.png
+  # faviconFile: ./spectaql/favicon.png
+  targetDir: ./target/book/spectaql
+  displayAllServers: true
+
+introspection:
+  removeTrailingPeriodFromDescriptions: false
+  schemaFile: ./frontend/schema.graphql
+  queryNameStrategy: capitalizeFirst
+  fieldExpansionDepth: 2
+
+  spectaqlDirective:
+    enable: true
+
+extensions:
+  graphqlScalarExamples: true
+
+info:
+  title: GraphQL API Reference
+  description: Welcome to the party!
+  termsOfService: https://www.example.com/terms
+  contact:
+    name: API Support
+    url: http://www.example.com/support
+    email: [email protected]
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+  x-introItems:
+    - title: Important thing 1
+      description: Some important stuff we wanted you to know. Supports `markdown`
+
+servers:
+  - url: https://staging.example.com/graphql
+    description: Staging
+  - url: https://auth-oidc.lab.element.dev/graphql
+    description: Production
+    production: true
+    headers:
+      - name: Authorization
+        example: Bearer <YOUR_TOKEN_HERE>
+        comment: Your foo from bar