Autogenerate Awesome GraphQL Documentation with SpectaQL
nordicapis
196 views
41 slides
Nov 06, 2023
Slide 1 of 41
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
About This Presentation
A presentation given by Christopher Newhouse, Software Engineer, Anvil Foundry, at our 2023 Platform Summit, October 17-18, 2023
Slide Content
Paperwork automation for product teams
with SpectaQL Auto-generate awesome GraphQL documentation
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 ‹#› useanvil.com
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 ‹#› useanvil.com
Software infrastructure to power the evolution of business processes from artifact-first to data-first. About Anvil ‹#›
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. ‹#› useanvil.com
What is SpectaQL? ‹#›
A powerful Node.js library for auto-generating static GraphQL docs with ease. SpectaQL is: ‹#› ‹#›
‹#› 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
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 ‹#› useanvil.com 36 k 975 + 1st 5
“All done, I just need to update the docs. Ugh…” The problem — Every API Developer @ Every Company ‹#›
‹#› 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…
The requirements ‹#›
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 ‹#› useanvil.com
The search ‹#›
‹#› useanvil.com
Choices, choices, choices ‹#› useanvil.com
SpectaQL ‹#› ‹#› useanvil.com
Selected features ‹#›
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 ‹#› useanvil.com 3 methods to provide your schema
This string contains `simple markdown` as well as a [ link to somewhere ]( https://your-website.com/somewhere ). Markdown is supported in all description fields ‹#› useanvil.com
Reference interpolation is available in all description fields I'm a description with a reference to [ myQuery ]( {{Queries.myQuery}} ) ‹#› useanvil.com
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) ‹#› useanvil.com
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 ‹#› useanvil.com
Metadata ‹#›
Specify the example value shown in your documentation Supported on Scalars, Fields, and Arguments Will be coerced appropriately Metadata: "example" ‹#› useanvil.com
Removes other references Boolean value Metadata: "undocumented" Supported everywhere Overrides the default visibility ‹#› Hide specific things
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 ‹#› useanvil.com
‹#› 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" }]) }
Themes ‹#›
Goals for themes ‹#› useanvil.com Complete customization Reduce project forking Easy to write Easy to consume
Overview ‹#› 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
Structure your-theme-dir/ ├── javascripts/ │ ├── stylesheets/ │ └── main.scss │ ├── views/ │ ├── partials/ │ ├── main.hbs │ └── embedded.hbs │ ├── helpers/ │ └── data/ └── index.js ‹#› useanvil.com
Example: Dark Theme ‹#› 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
‹#› useanvil.com
Getting started ‹#›
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 ‹#› useanvil.com
‹#› useanvil.com
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 } ‹#› useanvil.com
Thank you u seanvil.com github.com/anvilco/spectaql github: @newhouse [email protected]
Some Links and ❤️ ‹#› 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
Categories
BusinessDownload
Download Slideshow Get the original presentation fileQuick Actions
Statistics
- Views 196
- Slides 41
- Age 755 days
Related Slideshows
1
DTI BPI Pivot Small Business - BUSINESS START UP PLAN
MeljunCortes
28 views
1
CATHOLIC EDUCATIONAL Corporate Responsibilities
MeljunCortes
30 views
11
Karin Schaupp – Evocation; lançamento: 2000
alfeuRIO
28 views
10
Pillars of Biblical Oneness in the Book of Acts
JanParon
26 views
31
7-10. STP + Branding and Product & Services Strategies.pptx
itsyash298
27 views
44
Business Legislation PPT - UNIT 1 jimllpkggg
slogeshk98
29 views