Add a machine-readable GraphQL schema

Use the [built-in Rake Task available as part of the graphql-ruby
gem](https://github.com/rmosolgo/graphql-ruby/blob/master/lib/graphql/rake_task.rb)
in order to generate both
[IDL](https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51)
and JSON schema files.

Also adds a rake task that checks to make sure the files are up-to-date
as well as runs the rake task in our CI

.gitlab/ci/docs.gitlab-ci.yml

@@ -68,7 +68,7 @@ docs lint:
     # Check the internal anchor links
     - bundle exec nanoc check internal_anchors
-graphql-docs-verify:
+graphql-reference-verify:
   extends:
     - .only-ee
     - .default-tags
@@ -83,3 +83,4 @@ graphql-docs-verify:
   needs: ["setup-test-env"]
   script:
     - bundle exec rake gitlab:graphql:check_docs
+    - bundle exec rake gitlab:graphql:check_schema

doc/api/graphql/index.md

@@ -53,6 +53,11 @@ GitLab's GraphQL reference [is available](reference/index.md).
 It is automatically generated from GitLab's GraphQL schema and embedded in a Markdown file.
+Machine-readable versions are also available:
+
+- [JSON format](reference/gitlab_schema.json)
+- [IDL format](reference/gitlab_schema.graphql)
+
 ## GraphiQL
 The API can be explored by using the GraphiQL IDE, it is available on your

doc/development/api_graphql_styleguide.md

@@ -547,7 +547,7 @@ it 'returns a successful response' do
 end
 ```
-## Documentation
-For information on generating GraphQL documentation, see
-[Rake tasks related to GraphQL](rake_tasks.md#update-graphql-documentation).
+## Documentation and Schema
+For information on generating GraphQL documentation and schema files, see
+[Rake tasks related to GraphQL](rake_tasks.md#update-graphql-documentation-and-schema-definitions).

doc/development/rake_tasks.md

@@ -221,7 +221,7 @@ bundle exec rake db:obsolete_ignored_columns
 Feel free to remove their definitions from their `ignored_columns` definitions.
-## Update GraphQL Documentation
+## Update GraphQL Documentation and Schema definitions
 To generate GraphQL documentation based on the GitLab schema, run:
@@ -243,3 +243,13 @@ The actual renderer is at `Gitlab::Graphql::Docs::Renderer`.
 `@parsed_schema` is an instance variable that the `graphql-docs` gem expects to have available.
 `Gitlab::Graphql::Docs::Helper` defines the `object` method we currently use. This is also where you
 should implement any new methods for new types you'd like to display.
+
+### Update machine-readable schema files
+
+To generate GraphQL schema files based on the GitLab schema, run:
+
+```shell
+bundle exec rake gitlab:graphql:schema:dump
+```
+
+This uses graphql-ruby's built-in rake tasks to generate files in both [IDL](https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51) and JSON formats.

lib/tasks/gitlab/graphql.rake

@@ -2,10 +2,24 @@
 return if Rails.env.production?
+require 'graphql/rake_task'
+
 namespace :gitlab do
   OUTPUT_DIR = Rails.root.join("doc/api/graphql/reference")
   TEMPLATES_DIR = 'lib/gitlab/graphql/docs/templates/'
+  # Defines tasks for dumping the GraphQL schema:
+  # - gitlab:graphql:schema:dump
+  # - gitlab:graphql:schema:idl
+  # - gitlab:graphql:schema:json
+  GraphQL::RakeTask.new(
+    schema_name: 'GitlabSchema',
+    dependencies: [:environment],
+    directory: OUTPUT_DIR,
+    idl_outfile: "gitlab_schema.graphql",
+    json_outfile: "gitlab_schema.json"
+  )
+
   namespace :graphql do
     desc 'GitLab | Generate GraphQL docs'
     task compile_docs: :environment do
@@ -25,11 +39,20 @@ namespace :gitlab do
       if doc == renderer.contents
         puts "GraphQL documentation is up to date"
       else
-        puts '#' * 10
-        puts '#'
-        puts '# GraphQL documentation is outdated! Please update it by running `bundle exec rake gitlab:graphql:compile_docs`.'
-        puts '#'
-        puts '#' * 10
+        format_output('GraphQL documentation is outdated! Please update it by running `bundle exec rake gitlab:graphql:compile_docs`.')
+        abort
+      end
+    end
+
+    desc 'GitLab | Check if GraphQL schemas are up to date'
+    task check_schema: :environment do
+      idl_doc = File.read(Rails.root.join(OUTPUT_DIR, 'gitlab_schema.graphql'))
+      json_doc = File.read(Rails.root.join(OUTPUT_DIR, 'gitlab_schema.json'))
+
+      if idl_doc == GitlabSchema.to_definition && json_doc == GitlabSchema.to_json
+        puts "GraphQL schema is up to date"
+      else
+        format_output('GraphQL schema is outdated! Please update it by running `bundle exec rake gitlab:graphql:schema:dump`.')
         abort
       end
     end
@@ -42,3 +65,12 @@ def render_options
     template: Rails.root.join(TEMPLATES_DIR, 'default.md.haml')
   }
 end
+
+def format_output(str)
+  heading = '#' * 10
+  puts heading
+  puts '#'
+  puts "# #{str}"
+  puts '#'
+  puts heading
+end