docusaurus-graphql-plugin icon indicating copy to clipboard operation
docusaurus-graphql-plugin copied to clipboard

Replace the GitHub example with something else?

Open zhouzi opened this issue 3 years ago • 0 comments

Although most of the ideas come from GitHub's documentation, it turns out their APIs and documentation is very much opinionated. They are probably not a good example of a "vanilla" GraphQL API. A few examples are:

  • As pointed in #2, each mutation has a dedicated return type that's a wrapper over some other real types. For example addComment returns a AddCommentPayload object. So when documenting a mutation they show the detail of what's returned instead of linking to the object. And the types ending with Payload are not listed on the objects page.

It's hard to use them as a basic example as the result doesn't look that good. I do think that this plugin should offer options to get a similar result but it would be more advanced. Perhaps we should have a basic example using a simpler API and the advanced example using GitHub's, with the proper configuration.

zhouzi avatar Apr 16 '21 17:04 zhouzi