I was thinking about autogenerating GraphQL documentation from the schema, but also having the ability to add additional content.
I found a few projects that can do this among which SpectaQL seems the most promising. On top of documenting types/fields/queries, it offers static and dynamic examples, plain markdown content, extensive design customization, etc.
Alas, it seems that the initial curve might be a bit steeper as you have to find a way to somehow enrich your schema with metadata.
From what I was able to understand it seems that Absinthe offers enough extensibility to allow this to be built on top. However, a quick web search gave me the impression that no one has attempted to do this yet.
What are your approaches to documenting your GraphQL APIs, aside from describing fields/queries/types?
I think in this case it’s less about anything Absinthe specifically has, and more about GraphQL’s inherent introspection ability. Any GraphQL documentation tool would be wise to simply use introspection to get the GraphQL schema information and not anything specific to a particular implementation or language.
With that information someone can then format / display / amend any info they like. This is exactly the approach taken by SpectaQL, GitHub - anvilco/spectaql: Autogenerate static GraphQL API documentation. Note that the weaving they are talking about is weaving metadata into the introspection result, which is just JSON.
Thanks for the clarification. And what do I need to make Absinthe add this kind of metadata to the introspection results?
What I’m saying is that they post process the introspection results. They don’t ask the GraphQL implementation to add anything to the result, they take the result and add things to it.