type(docs): Update GraphQL document (support 3.11.0)

[suyeon-jung-dev]

Proposed changes

This PR adds:

• Replacing the GraphQL docs dociql with spectaql
  • It was created using spectaQL tool, customized similarly to a previous version of the GraphQL documents.
• Updating GraphQL docs v3.9.x and higher (3.9.x, 3.10.x, 3.11.x)
• Adding common error response information
• Update the latest version of GraphQL docs URL (v3.11.x) on Litmus Documentation Page (/litmus/experiments/api/contents)

Solved #4771

GraphQL API docs demo v3.9.0: https://suyeon-jung-dev.github.io/litmus/graphql/v3.9.0/api.html
GraphQL API docs demo v3.10.0: https://suyeon-jung-dev.github.io/litmus/graphql/v3.10.0/api.html
GraphQL API docs demo v3.11.0: https://suyeon-jung-dev.github.io/litmus/graphql/v3.11.0/api.html

Types of changes

What types of changes does your code introduce to Litmus? Put an x in the boxes that apply

• New feature (non-breaking change which adds functionality)
• Bugfix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update (if none of the other choices applies)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• I have read the CONTRIBUTING doc
• I have signed the commit for DCO to be passed.
• Lint and unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have added necessary documentation (if appropriate)

Dependency

• Please add the links to the dependent PR need to be merged before this (if any).

Special notes for your reviewer:

[suyeon-jung-dev]

Actually there is a thing I forgot to tell you guys.

To create with the spactaQL tool, we need to change one of Query/Mutation/Subscriptions to parent type.
You can see this commit.
The reason why we need to do this, I think the graphql/validation/validate.js library in spectaql couldn't generate with no-parent type of Query/Mutation/Subscription SDL files.

Do you guys think this method seems fine?

[neelanjan00]

@suyeon-jung-dev Here are a couple of things we should add:

• A window to try the API for a given server URL (similar to Swagger).
• Provide examples of success and failure cases while documenting them.

LMK if this sounds good?

[suyeon-jung-dev]

Hi, @neelanjan00 . If we need to add these two things, I'll look for other tools. Because SpectaQL doesn't support them.

• A window to try the API for a given server URL (similar to Swagger).
  SpectaQL supports only api end point paths like below.

• Provide examples of success and failure cases while documenting them
  SpectaQL supports only success case.

Thank you for your feedback :)

[neelanjan00]

Can you please check if you can find any tool that can help us achieve this? This will be very useful! Thanks!

[suyeon-jung-dev]

@suyeon-jung-dev Here are a couple of things we should add:

• A window to try the API for a given server URL (similar to Swagger).
• Provide examples of success and failure cases while documenting them.

LMK if this sounds good?

Hi @neelanjan00

I looked into the two things you asked about earlier, but I couldn't find any tools that have all the features we need. 🥲

The tool we previously used, dociql, is no longer being updated — its last update was 2 years ago. Additionally, dociql can only be installed in a Python 2 environment. Even if we were to continue using it, we would still need to create a config.yaml file manually, which requires typing out every line.

Regarding the feature "A window to try the API for a given server URL (similar to Swagger)," I have some concerns about potential security issues. We can also use GraphQL Playground for this purpose instead.

Considering all of this, I think SpectaQL is the best option.

[neelanjan00]

@suyeon-jung-dev Here are a couple of things we should add:

• A window to try the API for a given server URL (similar to Swagger).
• Provide examples of success and failure cases while documenting them.

LMK if this sounds good?

Hi @neelanjan00

I looked into the two things you asked about earlier, but I couldn't find any tools that have all the features we need. 🥲

The tool we previously used, dociql, is no longer being updated — its last update was 2 years ago. Additionally, dociql can only be installed in a Python 2 environment. Even if we were to continue using it, we would still need to create a config.yaml file manually, which requires typing out every line.

Regarding the feature "A window to try the API for a given server URL (similar to Swagger)," I have some concerns about potential security issues. We can also use GraphQL Playground for this purpose instead.

Considering all of this, I think SpectaQL is the best option.

Okay sure, I guess we can just document the various success and failure cases for each API. We can skip the Swagger-like interface in favour of the in-built GraphQL playground.

[namkyu1999]

Okay sure, I guess we can just document the various success and failure cases for each API. We can skip the Swagger-like interface in favour of the in-built GraphQL playground.

Hi @neelanjan00 , I tried to find many alternatives, but it seems unnecessary to create an error/success cases for every single request. (we already have success cases)

1. All open source that auto-generates GraphQL docs (DociQL, MagiDoc, SpectaQL...) make docs based on 'schema'.

In the case of an error, it depends on implementing the resolver function (not schema), so we have to check it manually to add it to the API docs for the error case. (It's time time-consuming job and hard to maintain)

2. Unlike REST API, GraphQL returns 200 OKs even in case of an error

All GraphQL queries and mutations return errors in a structure like List. In our codebase, we only return a single error. It also differs only in the message part of the error and does not return any other metadata or data.

• error Schema example (https://graphql.org/learn/validation/)
• multiple errors (https://gqlgen.com/reference/errors/#multiple-errors)

---

IMO, it would be much more efficient to add a page for common errors. This is because most errors coming from GraphQL servers are similar(authentication failure, MongoDB CRUD failure, etc.). SpectaQL supports adding pages using Markdown. So how about using this feature?

[neelanjan00]

Okay sure, I guess we can just document the various success and failure cases for each API. We can skip the Swagger-like interface in favour of the in-built GraphQL playground.

Hi @neelanjan00 , I tried to find many alternatives, but it seems unnecessary to create an error/success cases for every single request. (we already have success cases)

1. All open source that auto-generates GraphQL docs (DociQL, MagiDoc, SpectaQL...) make docs based on 'schema'.

In the case of an error, it depends on implementing the resolver function (not schema), so we have to check it manually to add it to the API docs for the error case. (It's time time-consuming job and hard to maintain)

2. Unlike REST API, GraphQL returns 200 OKs even in case of an error

All GraphQL queries and mutations return errors in a structure like List. In our codebase, we only return a single error. It also differs only in the message part of the error and does not return any other metadata or data.

• error Schema example (https://graphql.org/learn/validation/)
• multiple errors (https://gqlgen.com/reference/errors/#multiple-errors)

IMO, it would be much more efficient to add a page for common errors. This is because most errors coming from GraphQL servers are similar(authentication failure, MongoDB CRUD failure, etc.). SpectaQL supports adding pages using Markdown. So how about using this feature?

Sounds good, this is what I meant as well actually, sorry for the confusion if any. Yes, having some sort of documentation around the success and most common failure messages for at least the most common mutations and queries will be a good way forward.

[suyeon-jung-dev]

I deployed a demo using the branch feature/update-api-docs-3.9.1-deploy-test on my repository.

You can check 3.9.x, 3.10.x, 3.11.x version of GraphQL docs demo with those links.

Finally, the changes I made include:

1. Replacing the GraphQL docs dociql with spectaql
2. Updating GraphQL docs v3.9.x and higher (3.9.x, 3.10.x, 3.11.x)
3. Adding common error response information
4. Update the latest version of GraphQL docs URL (v3.11.x) on Litmus Documentation Page (/litmus/experiments/api/contents)

[Common Error Response page demo]

[namkyu1999]

LGTM 🚀