Commit 19ac5de0 authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'mjang-remove-duplicate-graphql-content' into 'master'

Remove duplicated content already in graphql-styleguide.md

See merge request gitlab-org/gitlab!45836
parents 3d409212 e3f465fd
......@@ -1984,86 +1984,3 @@ steps aren't required, consider setting up a [table](#tables) with headers of
Learn how to [document features deployed behind flags](feature_flags.md). For
guidance on developing GitLab with feature flags, see [Feature flags in development of GitLab](../feature_flags/index.md).
## GraphQL API
GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference
information is generated in our [GraphQL reference](../../api/graphql/reference/index.md).
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](../api_graphql_styleguide.md#graphiql).
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:
```markdown
# 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:
```markdown
## Set up the GraphiQL explorer
```
- Include a code block with the query that anyone can include in their
instance of the GraphiQL explorer:
````markdown
```graphql
query {
<insert queries here>
}
```
````
- Tell the user what to do:
```markdown
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](#save-the-image) section.
- 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](../../api/graphql/reference/index.md).
### Add the GraphQL example to the Table of Contents
You'll need to open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/).
We store our Table of Contents in the `default-nav.yaml` file, in the
`content/_data` subdirectory. You can find the GraphQL section under the
following line:
```yaml
- 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.
And that's all you need!
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment