Plugin: categorized documentation via tags

[Mikhus]

Since our GraphQL schema grows we become lacking of some way to organize docs when using graphiql.

Currently there is existing a split on Query, Mutation and Subscription only. BTW on a large schema would be good to have some ability to categorize somehow those Queries, Mutation and Subscriptions. For example some meta tags in descriptions of objects could be helpful to notify graphiql that it should group/categorize them, or at least search by them... Currently search in docs working against types/fields names only, not by description.

Let's imagine it could be something like:

"""Accounting entity @tag Payments"""
type Accounting implements Node {
  """The ID of an object"""
  id: ID!

  # ... other fields
}

"""Loan entity @tag Payments"""
type Loan implements Node {
   """The ID of an object"""
  id: ID!

  # ... other fields
}

# ...etc.

So now we could imagine, GraphiQL has an ability to organize docs in categories by @tag, or, at least @tag can be included in Docs explorer search...

Or, maybe, someone can point me to some existing known automated solution outside graphiql which can help us improve docs?

[benjie]

This needs greater discussion; so I've tagged it RFC (request for comments). I'd like a much more concrete proposal with details on how to parse the tags from the content and not cause issues with markdown/etc. I'd also like that this was opt-in so it could be a plugin for the new system (this also allows experimentation without breaking GraphiQL for others).

(I think we need something like this; large schemas are hard to browse. We must keep performance of managing them within GraphiQL in mind though - we cannot afford to significantly impact performance on already large schemas.)

[acao]

Hmm this is cool, @Mikhus possibly you should open an RFC for graphql-spec itself to adopt this? Then we and other specification-matching doc tools would adopt it.