GraphQL Voyager

Represent any GraphQL API as an interactive graph

GraphQL
graphql-kit/graphql-voyagerapis.guru/graphql-voyager/graphql-voyager

README

GraphQL Voyager


Represent any GraphQL API as an interactive graph. It's time to finally see the graph behind GraphQL.
You can also explore number of public GraphQL APIs from our list.

With graphql-voyager you can visually explore your GraphQL API as an interactive graph. This is a great tool when designing or discussing your data model. It includes multiple example GraphQL schemas and also allows you to connect it to your own GraphQL endpoint. What are you waiting for, explore your API!


_GraphQL Weekly #42_

Live Demo


voyager demo

Features


- Quick navigation on graph
- Left panel which provides more detailed information about every type
- "Skip Relay" option that simplifies graph by removing Relay wrapper classes
- Ability to choose any type to be a root of the graph

Usage


GraphQL Voyager exports Voyager React component and helper init function. If used without
module system it is exported as GraphQLVoyager global variable.

Properties


Voyager component accepts the following properties:

- introspection [object] - the server introspection response. If function is provided GraphQL Voyager will pass introspection query as a first function parameter. Function should return Promise which resolves to introspection response object.
- displayOptions _(optional)_
  - displayOptions.skipRelay [boolean, default true] - skip relay-related entities
  - displayOptions.skipDeprecated [boolean, default true] - skip deprecated fields and entities that contain only deprecated fields.
  - displayOptions.rootType [string] - name of the type to be used as a root
  - displayOptions.sortByAlphabet [boolean, default false] - sort fields on graph by alphabet
  - displayOptions.showLeafFields [boolean, default true] - show all scalars and enums
  - displayOptions.hideRoot [boolean, default false] - hide the root type
- allowToChangeSchema [boolean, default false] - allow users to change schema
- hideDocs [boolean, default false] - hide the docs sidebar
- hideSettings [boolean, default false] - hide settings panel
- hideVoyagerLogo [boolean, default true] - hide voyager logo

init function


The signature of the init function:

  1. ```js
  2. (hostElement: HTMLElement, options: object) => void
  3. ```

- hostElement - parent element
- options - is the JS object with properties ofVoyager component

Using pre-bundled version


You can get GraphQL Voyager bundle from the following places:

- jsDelivr
  - some exact version - https://cdn.jsdelivr.net/npm/graphql-voyager/v1.0.0-rc.15/voyager.min.js
  - latest version - https://cdn.jsdelivr.net/npm/graphql-voyager/dist/voyager.min.js
- from dist folder of the npm package graphql-voyager

The HTML with minimal setup (see the full example)

  1. ```html
  2. <!DOCTYPE html>
  3. <html>
  4.   <head>
  5.     <script src="https://cdn.jsdelivr.net/npm/react@16/umd/react.production.min.js"></script>
  6.     <script src="https://cdn.jsdelivr.net/npm/react-dom@16/umd/react-dom.production.min.js"></script>
  8.     <link
  9.       rel="stylesheet"
  10.       href="https://cdn.jsdelivr.net/npm/graphql-voyager/dist/voyager.css"
  11.     />
  12.     <script src="https://cdn.jsdelivr.net/npm/graphql-voyager/dist/voyager.min.js"></script>
  13.   </head>
  14.   <body>
  15.     <div id="voyager">Loading...</div>
  16.     <script>
  17.       // do a call to server using voyagerIntrospectionQuery provided
  18.       const query = GraphQLVoyager.voyagerIntrospectionQuery;
  19.       const introspection = fetch('<server url>', {
  20.         method: 'post',
  21.         headers: {
  22.           Accept: 'application/json',
  23.           'Content-Type': 'application/json',
  24.         },
  25.         body: JSON.stringify({ query }),
  26.         // ...
  27.       }).then((response) => response.json());
  28.       // or just return pre-fetched introspection
  30.       // Render <Voyager />
  31.       GraphQLVoyager.init(document.getElementById('voyager'), {
  32.         introspection: introspection,
  33.       });
  34.     </script>
  35.   </body>
  36. </html>
  37. ```

Using as a dependency


You can install lib using npm or yarn:

    npm i --save graphql-voyager
    yarn add graphql-voyager

And then use it:

  1. ```js
  2. import * as React from 'react';
  3. import * as ReactDOM from 'react-dom';
  4. import { Voyager, voyagerIntrospectionQuery } from 'graphql-voyager';

  6. const introspection = fetch(window.location.origin + '/graphql', {
  7.   method: 'post',
  8.   headers: { 'Content-Type': 'application/json' },
  9.   body: JSON.stringify({ query: voyagerIntrospectionQuery }),
  10. }).then((response) => response.json());

  12. ReactDOM.render(
  13.   <Voyager introspection={introspection} />,
  14.   document.getElementById('voyager'),
  15. );
  16. ```

Build for the web with webpack (example) or
browserify

Middleware


Graphql Voyager has middleware for the next frameworks:

Properties


Middleware supports the following properties:

- endpointUrl [string] - the GraphQL endpoint url.
- displayOptions [object] - same as here
- `headersJS` [`string`, default `"{}"`] - object of headers serialized in string to be used on endpoint url
  Note: You can also use any JS expression which results in an object with header names as keys and strings as values e.g. { Authorization: localStorage['Meteor.loginToken'] }

Express


  1. ```js
  2. import express from 'express';
  3. import { express as voyagerMiddleware } from 'graphql-voyager/middleware';

  5. const app = express();

  7. app.use('/voyager', voyagerMiddleware({ endpointUrl: '/graphql' }));

  9. app.listen(3001);
  10. ```

Hapi


Version 17+


  1. ```js
  2. import hapi from 'hapi';
  3. import { hapi as voyagerMiddleware } from 'graphql-voyager/middleware';

  5. const server = new Hapi.Server({
  6.   port: 3001,
  7. });

  9. const init = async () => {
  10.   await server.register({
  11.     plugin: voyagerMiddleware,
  12.     options: {
  13.       path: '/voyager',
  14.       endpointUrl: '/graphql',
  15.     },
  16.   });

  18.   await server.start();
  19. };

  21. init();
  22. ```

Koa


  1. ```js
  2. import Koa from 'koa';
  3. import KoaRouter from 'koa-router';
  4. import { koa as voyagerMiddleware } from 'graphql-voyager/middleware';

  6. const app = new Koa();
  7. const router = new KoaRouter();

  9. router.all(
  10.   '/voyager',
  11.   voyagerMiddleware({
  12.     endpointUrl: '/graphql',
  13.   }),
  14. );

  16. app.use(router.routes());
  17. app.use(router.allowedMethods());
  18. app.listen(3001);
  19. ```

Credits


This tool is inspired by graphql-visualizer project.