Creating a GraphQL example page

GraphQL APIs are different from RESTful APIs. Reference information is generated in our GraphQL API resources page.

However, it’s helpful to include examples on how to use GraphQL for different use cases, with samples that readers can use directly in the GraphiQL explorer.

This section describes the steps required to add your GraphQL examples to GitLab documentation.

Add a dedicated GraphQL page

To create a dedicated GraphQL page, create a new .md file in the doc/api/graphql/ directory. Give that file a functional name, such as import_from_specific_location.md.

Start the page with an explanation

Include a page title that describes the GraphQL functionality in a few words, such as: 

# Search for [substitute kind of data]

Describe the search. One sentence may be all you need. More information may help readers learn how to use the example for their GitLab deployments.

Include a procedure using the GraphiQL explorer

The GraphiQL explorer can help readers test queries with working deployments. Set up the section with the following:

  • Use the following title: 

    ## Set up the GraphiQL explorer

  • Include a code block with the query that anyone can include in their instance of the GraphiQL explorer: 

    ```graphql
query {
  <insert queries here>
}
```

  • Tell the user what to do: 

    1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`.
1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
1. Select **Play** to get the result shown here:
  • Include a screenshot of the result in the GraphiQL explorer. Follow the naming convention described in the Save the image section of the Documentation style guide.
  • Follow up with an example of what you can do with the output. Make sure the example is something that readers can do on their own deployments.
  • Include a link to the GraphQL API resources.

Add the GraphQL example to the global navigation

You should include a link for your new document in the global navigation (the list on the left side of the documentation website). To do so, open a second MR, against the GitLab documentation repository.

We store our global navigation in the navigation.yaml file, in the content/_data subdirectory. You can find the GraphQL section under the following line: 

- category_title: GraphQL

Be aware that CI tests for that second MR will fail with a bad link until the main MR that adds the new GraphQL page is merged. Therefore, only merge the MR against the gitlab-docs repository after the content has been merged and live on docs.gitlab.com.