Autogenerate Awesome GraphQL Documentation with SpectaQL
•Download as PPTX, PDF•
0 likes•10 views
A presentation given by Christopher Newhouse, Software Engineer, Anvil Foundry, at our 2023 Platform Summit, October 17-18, 2023
Recommended
Recommended
More Related Content
Similar to Autogenerate Awesome GraphQL Documentation with SpectaQL
Similar to Autogenerate Awesome GraphQL Documentation with SpectaQL (20)
More from Nordic APIs
More from Nordic APIs (20)
Recently uploaded
Recently uploaded (20)
Autogenerate Awesome GraphQL Documentation with SpectaQL
- 1. Paperwork automation for product teams
- 3. About me Previously at: Flexport, Datanyze, Yahoo, AdRoll Open Source: ● SpectaQL ● Objection.js ● Microfiber ● Graphql-to-json-schema ● Apollo-server-plugin-introspection-metadata ● Gatsby-plugin-segment-js Chris Newhouse Software Engineer at Anvil 3 useanvil.com
- 4. Agenda 01 Introduction 02 What is SpectaQL? 03 The Problem 04 The Requirements 05 The Search 06 Features* 08 Themes 09 Getting Started 10 Thank You 07 Metadata 4 useanvil.com
- 5. Software infrastructure to power the evolution of business processes from artifact-first to data-first. About Anvil 5
- 6. The Anvil Platform PDF Services Easy way to scalably generate and fill out PDFs Webforms Quickly spin up new forms and capture structured data Etch E-Sign Build signatures into your app Workflows Complete paperwork solution, from data to signed document. 6 useanvil.com
- 8. A powerful Node.js library for auto-generating static GraphQL docs with ease. SpectaQL is: 8 8
- 9. 9 GraphQL: • Single endpoint, usually implemented with a POST • Response is JSON and usually 200 OK • A complete Schema is required • Very Type-oriented REST: • Many endpoints, using the various HTTP Method Verbs (GET, POST, PUT, etc) • Responses types and codes can vary • No Schema required, but can be described using OpenAPI GraphQL vs REST
- 10. SpectaQL is popular and actively maintained Number of NPM downloads per week Number of stars on Github Most common rank among GraphQL documentation generators Average number of releases per month 10 useanvil.com 36k 975+ 1st 5
- 11. “All done, I just need to update the docs. Ugh…” The problem — Every API Developer @ Every Company 11
- 12. 12 Documentation is: • Hard • Annoying • Absolutely necessary Manual documentation processes: • Time consuming • Requires constant updating • Requires additional skill sets • Very hard to ensure completeness and accuracy Ahh, documentation…
- 14. Ideal characteristics Require as little extra work from the developer as possible Easy Various ways to provide the necessary data for various situations Flexible Must be able to be executed so it can be part of a build/deploy process Programmatic Hide things, arrange things, control "examples", colors, CSS and styles. Customizable No jumping back and forth between different areas Co-Located 14 useanvil.com
- 15. The search 15
- 16. 16 useanvil.com
- 20. SDL (Schema) File • Provide an SDL file with your Schema • Can provide multiple files to be stitched together Introspection Query against a live server • Hit a live server running your GraphQL schema • Supports Authorization Headers Introspection Query JSON • Provide a JSON representation of your Introspection Query results 20 useanvil.com 3 methods to provide your schema
- 21. This string contains `simple markdown` as well as a [link to somewhere](https://your-website.com/somewhere). Markdown is supported in all description fields 21 useanvil.com
- 22. Reference interpolation is available in all description fields I'm a description with a reference to [myQuery]({{Queries.myQuery}}) 22 useanvil.com
- 23. Build modes Development mode • Spins up a small, local HTTP server • Watches all relevant files • Re-builds and re-loads upon file changes JS & CSS loading modes • Load as separate resources • In-line with the HTML • Omit one or both altogether HTML output modes • Standalone / full • Embeddable ( <body> only) 23 useanvil.com
- 24. Specify logo and favicon • Feature your company's logo at the top of the docs • Add a favicon for browser tabs and bookmarks • Can provide hard-coded SVG data Branding Specify basic info • Title • Introduction • Contacts • License • …more Easily add additional introduction sections • Provide text/markdown • Provide path to file • Provide a URL 24 useanvil.com
- 25. Metadata 25
- 26. Specify the example value shown in your documentation ● Supported on Scalars, Fields, and Arguments ● Will be coerced appropriately Metadata: "example" 26 useanvil.com
- 27. Removes other references Boolean value Metadata: "undocumented" Supported everywhere Overrides the default visibility 27 Hide specific things
- 28. 3 methods to provide Metadata Woven into Introspection Query • Add to server response or JSON file • Can add at arbitrary key location • Supports deep nested paths • Check out: apollo-server-plugin-introspection-metadata Standalone JSON file • Simple structure • Arbitrary key location and depth allowed @spectaql Directive • Add directly to your SDL file(s) • Great for "SDL-First" approaches 28 useanvil.com
- 29. 29 useanvil.com @spectaql Directive type SomeType { number: Int @spectaql(options: [{ key: "example", value: "42" }]), randomNumber: Int, secretField: String @spectaql(options: [{ key: "undocumented", value: "true" }]) } type Query { publicQuery: SomeType, secretQuery: SomeType @spectaql(options: [{ key: "undocumented", value: "true" }]) }
- 30. Themes 30
- 31. Goals for themes 31 useanvil.com ● Complete customization ● Reduce project forking ● Easy to write ● Easy to consume
- 32. Overview 32 useanvil.com ● Simple directory structure ● Can override as much or as little as you want ● Views, layout, structure, HTML ● Data arrangement ● CSS ● Javascript ● Supports ESM modules
- 33. Structure your-theme-dir/ ├── javascripts/ │ ├── stylesheets/ │ └── main.scss │ ├── views/ │ ├── partials/ │ ├── main.hbs │ └── embedded.hbs │ ├── helpers/ │ └── data/ └── index.js 33 useanvil.com
- 34. Example: Dark Theme 34 useanvil.com # config.yml spectaql: # ... themeDir: ./node_modules/spectaql-dark-theme/theme # ... Install theme from NPM Add to your config file npm install --dev spectaql-dark-theme
- 35. 35 useanvil.com
- 37. Quick start using CLI For executing as a command Install SpectaQL from NPM Define your config file npm install -g spectaql # config.yml spectaql: logoFile: ./test/fixtures/logo.png faviconFile: ./test/fixtures/favicon.png introspection: schemaFile: ./examples/data/schema.gql info: title: GraphQL API Reference description: Our amazing GraphQL API servers: - url: https://example.com/graphql description: Production production: true 37 useanvil.com
- 38. 38 useanvil.com
- 39. Using the API If you need more control import { run } from 'spectaql' const spectaqlOptions = { specFile: 'path/to/your/config.yml', resolveWithOutput: true, } export default async function generateHtml () { const { html } = await run(spectaqlOptions) return html } 39 useanvil.com
- 41. Some Links and ❤️ 41 useanvil.com SpectaQL on Product Hunt SpectaQL on Hacker News SpectaQL on NPM SpectaQL on Nordic APIs SpectaQL on HackerNoon SpectaQL on StepZen SpectaQL on GitHub SpectaQL on GraphQL Editor SpectaQL on Atomic Object
Editor's Notes
- I don't maintain SpectaQL in my spare time, but rather Anvil lets me dedicate work hours towards it as necessary and appropriate. So I'll plug it real quick
- Go to dashboard
- A powerful, completely customizable Node library for auto-generating complete and beautiful static GraphQL documentation with ease. GraphQL only. Not REST, sorry.
- Seems like there's a lot of REST and OpenAPI focus here. And that's great. But what about GraphQL? Anyone used GraphQL? Anyone not used GraphQL? Anyone have an all-or-mostly GraphQL API?
- Have also been featured in Nordic APIs (!!!), Hacker News, Product Hunt, Reddit, and more
- What good is your API if nobody knows it's there? Or how to use it? Or if it's not up to date?
- GraphQL has a defined schema! We should be able to leverage this. Especially with GraphQL Tools JS
- GraphiQL GraphQL Playground DociQL None had all the things we wanted: too rigid on inputs too rigid on customization not able to execute via CLI not easy to access output So we decided to make our own…
- And so SpectaQL was born!
- Have some cool formatting.
- Reference any Queries, Mutations, Types or Subscriptions.
- Boolean Value: A simple Boolean Indicator Supported Everywhere: Types Fields Arguments Enums Queries Mutations Overrides the Default visibility: Will "hide" an item when the default was to show it, and vice versa. Useful for 1-off overriding of the default behavior. Removes other references: Will intelligently remove things that are no longer referenced. E.g if you remove type Foo, fields and arguments with Foo as the underlying type will also be removed.
- ### `javascripts` Any files you add to this folder will be concatenated and then minified into the `spectaql.min.js` file of your build's target directory along with the default files. If you want to simply add an additional JS file to your build, this is your way. Just add it to this folder in your theme directory. You can also replace/overwrite any of SpectaQL's default javascript files. ### `stylesheets` Any `.css` files that you add to this folder will be concatenated and minified into the `spectaql.min.css` file of your build's target directory along with the default CSS. SpectaQL supports SCSS, and the default CSS is built by processing `main.scss` in the default theme's `stylesheets/` directory. If your theme provides a `main.scss` file, it will completely replace the default theme and be used to direct the SCSS -> CSS build. You can then import other `.scss` files from your own custom `main.scss` file. ### `views` SpectaQL uses [Handlebars][handlebars] as its templating engine - please read up on their docs if you'd like to alter this area. Any `.hbs` files that you add to this folder will be overlayed on top of the default theme's directory. SpectaQL will look for the the `main.hbs` file in the resulting `views` directory as the entry point for Handlebars. If your theme provides a `main.hbs` file, that will overwrite the default one and be used to direct the HBS -> HTML build. If you only want to tweak and/or add certain partials, you can do so by only including those customized or additional files in your theme. They will be overlayed on top of the default theme directory in a supplemental manner. SpectaQL also supports running a theme in "embeddable" mode to produce output that can be embeded into an existing HTML page. In "embeddable" mode, the `embedded.hbs` file will be used as the entry point for Handlebars. Depending on the changes you've made, if you want your theme to support "embeddable" mode properly you may need to customize the `embedded.hbs` file in your theme. ### `helpers` [Handlebars][handlebars] allows for Javascript "helpers" to be used throughout its templates. These helpers must exist in the `helpers/` directory. All of SpectaQL's default theme helpers will be available to any custom theme "for free". If you'd like to add more helpers or overwrite an existing helper, simply put your JS file(s) into this folder and they will be copied on top of the default theme's directory and will be available for use in your templates. ### `data` _NOTE:_ This is an experimental API and it could change in a breaking manner at any time before "major" release. Use at your own risk! By default, SpectaQL will use all the non-hidden data that your GraphQL schema has provided, and arrange it in an sane, but opinionated default manner. It will group `Queries` and `Mutations` under an `Operations` header, then it will display all regular `Types`, and finally it will display all `Subscriptions`. You can see the [default arranger source][default-data-arranger] for more on how the default is done. However, if you'd like to completely customize the data that's displayed, and have some basic control over how it's displayed, you can provide a "dynamic data arranger" module. Here's how: - Create your dynamic data arranger module. It should export a function that expects the same arguments that are provided in the [example dynamic data arranger][custom-data-arranger] - Save it to `data/index.js` in your theme directory. _NOTE:_ Again, this is an experimental API and it could change in a breaking manner at any time before "major" release. Use at your own risk!
- This theme contains just a single file!
- Many of the options supported in the config yaml can be specified via CLI options.
- Just a few lines of code. Development mode will spin up a server for you. Watches for changes and will refresh.
- Easy to use the API in Node.