Merge branch '30082-graphql-schema' into 'master'

Add a machine-readable graphql schema

See merge request gitlab-org/gitlab!19199

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

@@ -67,7 +67,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
@@ -82,3 +82,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

@@ -551,7 +551,7 @@ it 'returns a successful response' do
 end
 ```
 
-## Documentation
+## Documentation and Schema
 
-For information on generating GraphQL documentation, see
-[Rake tasks related to GraphQL](rake_tasks.md#update-graphql-documentation).
+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