Skip to content

Improve Graphql Docs

Felipe Artur requested to merge issue_57694 into master

What does this MR do?

Introduces a rake task to generate GraphQL documentation based on GitLab schema. In the current state
it is only generating output for GraphQL objects and placing it on docs/api/graphql/index.md.

This uses some features from graphql-docs gem like its schema parser and helper methods. The docs generator code comes from our side giving us more flexibility, like using Haml templates and generating markdown files.

How to use it

Docs can be generated using bundle exec rake gitlab:graphql:compile_docs.
The docs output directory and template file can be changed directly on that rake task.

This merge request already have the generated content. To view it checkout to this branch and access:
http://your_local_instance/help/api/graphql/reference/index.md

Next steps

If we choose to go forward with this implementation we should take into account taking additional steps to make sure the generated documentation is always useful and up to date.

  • Use a rubocop rule to always add descriptions to GraphQL resources on GitLab schema
  • Use alert bot to make sure changes made directly into the generated docs are not merged
  • Use alert bot to remind when documentation is outdated
  • It should be simple to change the templates and add more resources to our generator but we should have some docs to help other developers do it.
  • Add more GraphQL resources to templates like mutations, queries, interfaces, deprecation messages, alerts etc.
  • Allow to use Haml partials template files to be included, right now we have one single page for Graphql objects. We should have one page for each resource type.

closes #57694 (closed)

Edited by Felipe Artur

Merge request reports