dociql VS stepzen-spectaql-docs

Magidoc is a GraphQL documentation generator

SpectaQL was originally forked from a project called DociQL to add some enhancements there. And DociQL was originally forked from a project called Spectacle to make it work with GraphQL. And (finally) Spectacle was designed to work with Swagger/OpenAPI. Swagger/OpenAPI is a specification designed to help standardize the description of REST APIs with many routes, and uses JSON Schema as the way to define Data Types/Models. This means that SpectaQL had to wrestle with several layers of history and transformations; making SpectaQL's enhancements fit into the DociQL world, which in turn had to make things fit into the Spectacle/Swagger/OpenAPI world.

There was one solution we found that was the closest to what we were looking for: DociQL. It's an open-source, node.js project that describes itself like this: "DociQL generates beautiful static HTML5 documentation from a GraphQL endpoint using the introspection query." Awesome!

There have been several articles written about it, like this one and this one

If you want to add documentation to your SDL after this step, StepZen can help you do that in a low-code way as well.

What comes next? So far, you've learned how to create static documentation based on a GraphQL API locally, but the next step would be to integrate this into your CI/CD and deploy this documentation on a server. Combining with your CI/CD can be done by adding the command to run SpectaQL to your deployment steps. At the same time, StepZen can be integrated with Netlify to deploy the static documentation. You can find the repository with the complete source code for this post here.