Add graphql docs generator

.gitlab-ci.yml

@@ -30,6 +30,14 @@ rubocop:
   script:
     - bundle exec rubocop
 
+graphql_docs:
+  extends:
+    - .rails
+  stage: lint
+  script:
+    - bundle exec rake graphql:compile_docs
+    - git diff --exit-code
+
 rspec:
   extends:
     - .rails

Gemfile

@@ -38,6 +38,8 @@ group :development, :test do
   # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
   gem 'debug', platforms: %i[mri windows]
 
+  gem 'graphql-docs', '~> 4.0'
+
   gem 'rspec-rails', '~> 6.0'
 
   gem 'factory_bot_rails', '~> 6.2'

Gemfile.lock

@@ -85,9 +85,11 @@ GEM
       msgpack (~> 1.2)
     builder (3.2.4)
     coderay (1.1.3)
+    commonmarker (0.23.10)
     concurrent-ruby (1.2.2)
     connection_pool (2.4.1)
     crass (1.0.6)
+    dartsass (1.49.8)
     database_cleaner-active_record (2.1.0)
       activerecord (>= 5.a)
       database_cleaner-core (~> 2.0.0)
@@ -103,15 +105,30 @@ GEM
     drb (2.2.0)
       ruby2_keywords
     erubi (1.12.0)
+    escape_utils (1.3.0)
+    extended-markdown-filter (0.7.0)
+      html-pipeline (~> 2.9)
     factory_bot (6.4.2)
       activesupport (>= 5.0.0)
     factory_bot_rails (6.4.2)
       factory_bot (~> 6.4)
       railties (>= 5.0.0)
+    gemoji (3.0.1)
     globalid (1.2.1)
       activesupport (>= 6.1)
     graphql (2.1.6)
       racc (~> 1.4)
+    graphql-docs (4.0.0)
+      commonmarker (~> 0.23, >= 0.23.6)
+      dartsass (~> 1.49)
+      escape_utils (~> 1.2)
+      extended-markdown-filter (~> 0.4)
+      gemoji (~> 3.0)
+      graphql (~> 2.0)
+      html-pipeline (~> 2.14, >= 2.14.3)
+    html-pipeline (2.14.3)
+      activesupport (>= 2)
+      nokogiri (>= 1.4)
     i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     io-console (0.6.0)
@@ -323,6 +340,7 @@ DEPENDENCIES
   declarative_policy (~> 1.1)
   factory_bot_rails (~> 6.2)
   graphql (~> 2.1)
+  graphql-docs (~> 4.0)
   lograge (~> 0.14.0)
   pg (~> 1.1)
   puma (>= 5.0)

app/graphql/mutations/echo.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mutations
+  class Echo < BaseMutation
+    description <<~DOC
+      A mutation that does not perform any changes.
+
+      This is expected to be used for testing of endpoints, to verify
+      that a user has mutation access.
+    DOC
+
+    argument :errors,
+             type: [::GraphQL::Types::String],
+             required: false,
+             description: 'Errors to return to the user.'
+
+    argument :message,
+             type: ::GraphQL::Types::String,
+             required: false,
+             description: 'Message to return to the user.'
+
+    field :message,
+          type: ::GraphQL::Types::String,
+          null: true,
+          description: 'Message returned to the user.'
+
+    def resolve(**args)
+      args
+    end
+  end
+end

app/graphql/types/mutation_type.rb

@@ -9,14 +9,6 @@ class MutationType < Types::BaseObject
     mount_mutation Mutations::Users::Login
     mount_mutation Mutations::Users::Logout
     mount_mutation Mutations::Users::Register
-
-    field :echo, GraphQL::Types::String, null: false,
-                                         description: 'Field available for use to test mutation API access' do
-      argument :message, GraphQL::Types::String, required: true, description: 'String to echo as response'
-    end
-
-    def echo(message:)
-      message
-    end
+    mount_mutation Mutations::Echo
   end
 end

docs/graphql/index.md

@@ -0,0 +1,7 @@
+---
+title: GraphQL Schema
+---
+
+The GraphQL Schema is documented on these pages.
+
+Entrypoint for all queries is the [`Query` type](object/query.md).

docs/graphql/interface/node.md

@@ -0,0 +1,13 @@
+---
+title: Node
+---
+
+An object with an ID.
+
+
+## Fields without arguments
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | [`ID!`](../scalar/id.md) | ID of the object. |
+

docs/graphql/mutation/echo.md

@@ -0,0 +1,25 @@
+---
+title: echo
+---
+
+A mutation that does not perform any changes.
+
+This is expected to be used for testing of endpoints, to verify
+that a user has mutation access.
+
+
+## Arguments
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clientMutationId` | [`String`](../scalar/string.md) | A unique identifier for the client performing the mutation. |
+| `errors` | [`[String!]`](../scalar/string.md) | Errors to return to the user. |
+| `message` | [`String`](../scalar/string.md) | Message to return to the user. |
+
+## Fields
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clientMutationId` | [`String`](../scalar/string.md) | A unique identifier for the client performing the mutation. |
+| `errors` | [`[String!]!`](../scalar/string.md) | Errors encountered during execution of the mutation. |
+| `message` | [`String`](../scalar/string.md) | Message returned to the user. |

docs/graphql/mutation/userslogin.md

@@ -0,0 +1,22 @@
+---
+title: usersLogin
+---
+
+Login to an existing user
+
+## Arguments
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clientMutationId` | [`String`](../scalar/string.md) | A unique identifier for the client performing the mutation. |
+| `email` | [`String`](../scalar/string.md) | Email of the user |
+| `password` | [`String!`](../scalar/string.md) | Password of the user |
+| `username` | [`String`](../scalar/string.md) | Username of the user |
+
+## Fields
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clientMutationId` | [`String`](../scalar/string.md) | A unique identifier for the client performing the mutation. |
+| `errors` | [`[String!]!`](../scalar/string.md) | Errors encountered during execution of the mutation. |
+| `userSession` | [`UserSession`](../object/usersession.md) | The created user session |

docs/graphql/mutation/userslogout.md

@@ -0,0 +1,20 @@
+---
+title: usersLogout
+---
+
+Logout an existing user session
+
+## Arguments
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clientMutationId` | [`String`](../scalar/string.md) | A unique identifier for the client performing the mutation. |
+| `userSessionId` | [`UserSessionID!`](../scalar/usersessionid.md) | ID of the session to logout |
+
+## Fields
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clientMutationId` | [`String`](../scalar/string.md) | A unique identifier for the client performing the mutation. |
+| `errors` | [`[String!]!`](../scalar/string.md) | Errors encountered during execution of the mutation. |
+| `userSession` | [`UserSession`](../object/usersession.md) | The logged out user session |

docs/graphql/mutation/usersregister.md

@@ -0,0 +1,22 @@
+---
+title: usersRegister
+---
+
+Register a new user
+
+## Arguments
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clientMutationId` | [`String`](../scalar/string.md) | A unique identifier for the client performing the mutation. |
+| `email` | [`String!`](../scalar/string.md) | Email of the user |
+| `password` | [`String!`](../scalar/string.md) | Password of the user |
+| `username` | [`String!`](../scalar/string.md) | Username of the user |
+
+## Fields
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clientMutationId` | [`String`](../scalar/string.md) | A unique identifier for the client performing the mutation. |
+| `errors` | [`[String!]!`](../scalar/string.md) | Errors encountered during execution of the mutation. |
+| `user` | [`User`](../object/user.md) | The created user |

docs/graphql/object/query.md

@@ -0,0 +1,44 @@
+---
+title: Query
+---
+
+Root Query type
+
+## Fields without arguments
+
+| Name | Type | Description |
+|------|------|-------------|
+| `currentAuthorization` | [`Authorization`](../union/authorization.md) | Get the currently logged in authorization |
+| `currentUser` | [`User`](../object/user.md) | Get the currently logged in user |
+
+## Fields with arguments
+
+### echo
+
+Field available for use to test API access
+
+Returns [`String!`](../scalar/string.md).
+
+| Name | Type | Description |
+|------|------|-------------|
+| `message` | [`String!`](../scalar/string.md) | String to echo as response |
+
+### node
+
+Fetches an object given its ID.
+
+Returns [`Node`](../interface/node.md).
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | [`ID!`](../scalar/id.md) | ID of the object. |
+
+### nodes
+
+Fetches a list of objects given a list of IDs.
+
+Returns [`[Node]`](../interface/node.md).
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ids` | [`[ID!]!`](../scalar/id.md) | IDs of the objects. |

docs/graphql/object/user.md

@@ -0,0 +1,16 @@
+---
+title: User
+---
+
+Represents a user
+
+## Fields without arguments
+
+| Name | Type | Description |
+|------|------|-------------|
+| `createdAt` | [`Time!`](../scalar/time.md) | Time when this User was created |
+| `email` | [`String!`](../scalar/string.md) | Email of the user |
+| `id` | [`UserID!`](../scalar/userid.md) | GlobalID of the user |
+| `updatedAt` | [`Time!`](../scalar/time.md) | Time when this User was last updated |
+| `username` | [`String!`](../scalar/string.md) | Username of the user |
+

docs/graphql/object/usersession.md

@@ -0,0 +1,17 @@
+---
+title: UserSession
+---
+
+Represents a user session
+
+## Fields without arguments
+
+| Name | Type | Description |
+|------|------|-------------|
+| `active` | [`Boolean!`](../scalar/boolean.md) | Whether or not the session is active and can be used |
+| `createdAt` | [`Time!`](../scalar/time.md) | Time when this UserSession was created |
+| `id` | [`UserSessionID!`](../scalar/usersessionid.md) | GlobalID of the user |
+| `token` | [`String`](../scalar/string.md) | Token belonging to the session, only present on creation |
+| `updatedAt` | [`Time!`](../scalar/time.md) | Time when this UserSession was last updated |
+| `user` | [`User!`](../object/user.md) | User that belongs to the session |
+

docs/graphql/scalar/boolean.md

@@ -0,0 +1,5 @@
+---
+title: Boolean
+---
+
+Represents `true` or `false` values.

docs/graphql/scalar/id.md

@@ -0,0 +1,5 @@
+---
+title: ID
+---
+
+Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"VXNlci0xMA=="`) or integer (such as `4`) input value will be accepted as an ID.

docs/graphql/scalar/string.md

@@ -0,0 +1,5 @@
+---
+title: String
+---
+
+Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.

docs/graphql/scalar/time.md

@@ -0,0 +1,8 @@
+---
+title: Time
+---
+
+Time represented in ISO 8601.
+
+For example: "2023-12-15T17:31:00Z".
+

docs/graphql/scalar/userid.md

@@ -0,0 +1,5 @@
+---
+title: UserID
+---
+
+A unique identifier for all User entities of the application

docs/graphql/scalar/usersessionid.md

@@ -0,0 +1,5 @@
+---
+title: UserSessionID
+---
+
+A unique identifier for all UserSession entities of the application

docs/graphql/union/authorization.md

@@ -0,0 +1,9 @@
+---
+title: Authorization
+---
+
+Objects that can present an authorization
+
+## Possible types
+
+- [`UserSession`](../object/usersession.md)

docs/index.mdx

@@ -0,0 +1,16 @@
+---
+title: Welcome to the Documentation for Sagittarius
+description: Find out how the backend works
+template: splash
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+Sagittarius provides a GraphQL API.
+
+<CardGrid stagger>
+  <Card title='<a href="graphql/">GraphQL Schema</a>' icon="document">
+    View the documentation for the graphql schema.
+  </Card>
+</CardGrid>
+