Show HN: SpectaQL – auto-generate GraphQL API documentation (opens in new tab)

(github.com)

51 pointsmrbogle5y ago13 comments

13 comments

I've been using DociQL in an automated pipeline and its been handy! Should be easy to give this a go at some point in the near future.

I made a similar change for the introspection url being set dynamically on main line dociql, so good to see it there as well.

mrbogleOP5y ago

We added a number of things that came to mind while trying to get our docs dialed in ourselves. Glad to see that others were looking for these same enhancements! Let us know if you run into any issues

newhouse5y ago

Thanks for the comment! We added a lot of things that came to mind while trying to get our docs dialed in ourselves. Glad to see that others were looking for these same enhancements!

mrbogleOP5y ago

Hey all, we couldn't find exactly what we wanted in a documentation generator, so we wrote our own. Let us know if you have any questions!

hirundo5y ago

I appreciate the integrated examples. I wish I had your example generator before I rolled my own.

The documention generator we currently use isn't scaling well with 100+ types and 800+ mutations. It makes the sidebar too unwieldy. It looks like SpectaQL has the same issue. Not sure there's a great solution while keeping to static pages.

Thanks much for the open license. I hope to try it soon.

We might pay for a searchable hosted white label version.

mrbogleOP5y ago

Thanks for the feedback! Yeah I can see how it could get out of hand with that many types and mutations. The single page situation would probably break down in that scenario too. We'll think about how it might be able to scale. Feel free to open an issue on the repo and we can work it out together.

1 more reply

bretthopper5y ago

We quickly ran into the same issue at Shopify. We've since moved from a flat list into sections by "domains"; within each section is the breakdown by type. You can see it here: https://shopify.dev/docs/admin-api/graphql/reference

Of course this grouping has to be done a little manually. And it's not perfect, but definitely better than the flat alternative. For reference, we have thousands of types.

1 more reply

newhouse5y ago

Thanks for the kind words! I wrote most of the enhancements and thought the static and dynamic example support was crucial to have.

Our schema is not as big as yours, but I could see how things could get a bit unwieldy on the navbar. Come on over to the repo and we can work on a solution together - I'm sure there's something we can figure out if we put on our design + product + engineer hats.

linkdd5y ago

Amazing, our free trial of GraphQL Editor that we used only for its documentation generator ended, so this is literal a time/money saver.

Thank you!

EDIT: Have you thought about accepting Github sponsorships[1]?

[1] - https://github.com/sponsors

mrbogleOP5y ago

That's great to hear it'll be useful!

Thanks for the heads up on sponsorships, we hadn't thought about accepting them. Currently the project is effectively funded by us at useanvil.com, but we'll talk about opening that up!

j / k navigate · click thread line to collapse

13 comments

okaramian5y ago

I've been using DociQL in an automated pipeline and its been handy! Should be easy to give this a go at some point in the near future.

I made a similar change for the introspection url being set dynamically on main line dociql, so good to see it there as well.

mrbogleOP5y ago

newhouse5y ago

Thanks for the comment! We added a lot of things that came to mind while trying to get our docs dialed in ourselves. Glad to see that others were looking for these same enhancements!

mrbogleOP5y ago

Hey all, we couldn't find exactly what we wanted in a documentation generator, so we wrote our own. Let us know if you have any questions!

hirundo5y ago

I appreciate the integrated examples. I wish I had your example generator before I rolled my own.

Thanks much for the open license. I hope to try it soon.

We might pay for a searchable hosted white label version.

mrbogleOP5y ago

1 more reply

bretthopper5y ago

Of course this grouping has to be done a little manually. And it's not perfect, but definitely better than the flat alternative. For reference, we have thousands of types.

1 more reply

newhouse5y ago

Thanks for the kind words! I wrote most of the enhancements and thought the static and dynamic example support was crucial to have.

linkdd5y ago

Amazing, our free trial of GraphQL Editor that we used only for its documentation generator ended, so this is literal a time/money saver.

Thank you!

EDIT: Have you thought about accepting Github sponsorships[1]?

[1] - https://github.com/sponsors

mrbogleOP5y ago

That's great to hear it'll be useful!

Thanks for the heads up on sponsorships, we hadn't thought about accepting them. Currently the project is effectively funded by us at useanvil.com, but we'll talk about opening that up!

j / k navigate · click thread line to collapse