Discussion: Should SpectaQL break away from Swagger / OpenAPI?

SpectaQL’s roots come from Dociql, which comes from Spectacle.

Spectaqle’s docs state:

Spectacle generates beautiful static HTML5 documentation from OpenAPI/Swagger 2.0 API specifications.

Because of this, there is a LOT of Swagger/OpenAPI specific stuff going on under the hood in SpectaQL:

• The GraphQL schema is converted in to a JSON Schema…
• There are many terms and handlebars templates that follow a JSON/Swagger naming and structuring convention…
• etc…

I’ve been developing SpectaQL for a while now, where I’m pretty confident that I want to throw away all of the legacy JSON/Swagger/OpenAPI internals as much as possible.

It’s just a headache to squeeze things into the JSON Schema, and there are loopholes and caveats and workarounds starting to pop up more and more, and really there’s not much more that I need other than an Introspection Query object and a GraphQL schema (one can be generated from the other, and vice versa).

There’s also really not much that’s exposed to the user anymore that is Swagger-esque. Only a few of the silly parts of the config.yml (servers and info) still resemble or come from the Swagger/OpenAPI…but they’re very generic things that are stored in there.

Sure, there are some internals that still boil things down to Swagger, but they’re private and not supposed to be touched by userland.

Shall I rip it all out and revamp things when I’ve got the time?

[AubSs]

Definitely, Swagger/OpenAPI don’t seem to be useful for graphql.

By the way, you’ve created a great product!

[newhouse]

Our fork is for some custom internal integrations to add some extra links into the docs for finding source resolver info that’s specific to a custom GQL server implementation we use. Nothing particularly useful for the community as a whole on its own. However, a pluggable/extensible architecture could go a long ways in making it easier to extend v. fork in the future (if it doesn’t exist yet?). Looking forward to checking out your work in 1.0!

@mcwoodle you might be able to accomplish what you want with:

• Intro Items
• Or, by creating a lightweight “theme” of your own where you edit/add the appropriate Handlebars template file.

Good luck!