Add GraphQL directives to new GraphQL docs

Luke Duncalferequested to merge
593121-directives into master

What does this MR do and why?

This MR adds GraphQL directives to the new GraphQL docs.

It is part of a series of MRs to move across the work in !130378 (closed) in smaller pieces.

Previous MRs:

MR Description
!243355 (merged) Enums
!250737 (merged) Scalars
!251517 (merged) Input Objects

References

Split GraphQL API reference documentation into ... (#593121)

How to set up and validate locally

You can review the generated docs for this MR:

Try changing a GraphQL directive locally, for example:

diff --git a/app/graphql/directives/authz/granular_scope.rb b/app/graphql/directives/authz/granular_scope.rb
index 2e2586c977a2..c3b2217103ff 100644
--- a/app/graphql/directives/authz/granular_scope.rb
+++ b/app/graphql/directives/authz/granular_scope.rb
@@ -7,7 +7,7 @@ class GranularScope < GraphQL::Schema::Directive

       argument :permissions, [GraphQL::Types::String],
         required: false,
-        description: 'Granular scope permissions required to access the field or type.'
+        description: 'Granular scope permissions required to access the field or type. Test.'

       argument :boundary_type, Types::Authz::AccessTokens::BoundaryEnum,
         required: false,

Then run the check docs rake task:

bundle exec rake gitlab:graphql:docs:check

It should detect that there are changes that haven't been committed to the compiled docs:

##########
#
# Experimental GraphQL documentation is outdated!
# Please update the documentation by running `bundle exec rake gitlab:graphql:docs:compile`.
#
##########

Now compile the docs:

bundle exec rake gitlab:graphql:docs:compile

It should compile successfully:

Experimental documentation compiled.

And run :check again, it should pass this time:

Experimental GraphQL documentation is up to date.

Check that the change to doc/api/graphql/reference/experimental/directives.md looks correct:

git diff doc/api/graphql/reference/experimental/directives.md

The diff should be:

diff --git a/doc/api/graphql/reference/experimental/directives.md b/doc/api/graphql/reference/experimental/directives.md
index dcdf06a1f516..3a9b2933dd88 100644
--- a/doc/api/graphql/reference/experimental/directives.md
+++ b/doc/api/graphql/reference/experimental/directives.md
@@ -81,7 +81,7 @@ Marks a field as introduced in a specific version. Fields with a version higher
 | `boundary` | [`String`](scalars.md#string) | Method name to call on the resolved object to extract the authorization boundary (Project/Group). Use when the object is already resolved (fields on types, nested fields). |
 | `boundaryArgument` | [`String`](scalars.md#string) | Argument name containing the authorization boundary (path or GlobalID). Use for mutations and query fields where the boundary is passed as an argument. |
 | `boundaryType` | [`PermissionBoundary`](enums.md#permissionboundary) | The type of authorization boundary (project, group, user, instance). Used for validation and documentation of the permission boundary. |
-| `permissions` | [`[String!]`](scalars.md#string) | Granular scope permissions required to access the field or type. |
+| `permissions` | [`[String!]`](scalars.md#string) | Granular scope permissions required to access the field or type. Test. |
 | `requirementGroup` | [`String`](scalars.md#string) | Label grouping directives that are alternative boundaries for the same requirement. The token must be authorized on any one boundary in a group, and on every group. Absent means the primary group. Set for a second container, such as a move target. |
 | `skipReason` | [`String`](scalars.md#string) | Reason the field or type intentionally opts out of granular token authorization. |

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Related to #593121

Edited by Luke Duncalfe

Merge request reports