Documenting a graphQL API like GitHub


#1

Just wondering if anyone knows of any packages that generate (ideally dynamic) documentation for a graphQL API like GitHub does. Until know I’ve found this npm package but would like to hear about best practices (besides having the graphiQL) since pointing to run introspect queries in the documentation seems too “advanced” for people that would like to know how the data looks like in graphQL


#2

If you don’t want to use GraphiQL, and don’t want to generate the docs yourself, then using something like graphql-docs can work. That being said it’s not that hard to generate the docs yourself dynamically. GitHub actually mentioned this as being one of the reasons why they went with GraphQL in their announcement blog post. Take a quick look at the source of graphql-docs to get an idea of what’s involved.


#3

Yes, have seen that already but graphql-docs is still very simple compared to what github already offers in terms of navigation or display. I was not sure if their documentation was based on some open-sourced package, but seems like it’s not open for now(or I couldn’t find it).


#4

I’m pretty sure GitHub is generating those docs themselves - I haven’t heard of them open sourcing their GraphQL doc generation process (yet), and I don’t see anything over on their BitBucket account … (just throwing in a bit of Monday morning git humour - hilarious stuff :slight_smile: ).


#5

Thanks for the effort! Haven’t thought about checking their Bitbucket account :smile:


#6

Unfortunately, their docs are already a little outdated, at least they were when @helfer checked them out. There’s been some interest in the GraphQL slack channel in this.

I’d be really interested if someone started a project like this, since we might have some public GraphQL APIs of our own soon that we will need to document.