GraphQLDocs
Easily generate beautiful documentation from your GraphQL schema.
Installation
Add this line to your application's Gemfile:
gem 'graphql-docs'
And then execute:
$ bundle
Or install it yourself as:
$ gem install graphql-docs
Usage
Simple! Call GraphQLDocs.generate
, taking care to pass in the GraphQL endpoint:
GraphQLDocs.build(url: 'http://graphql.org/swapi-graphql/')
If your GraphQL endpoint requires authentication, you can provide a username or password, or an access token:
options = {
url: 'http://graphql.org/swapi-graphql/'
login: 'gjtorikian',
password: 'lolnowai'
}
GraphQLDocs.build(options)
options = {
url: 'http://graphql.org/swapi-graphql/'
access_token: 'something123'
}
GraphQLDocs.build(options)
If you already have the JSON locally, great! Call the same method with path
instead:
GraphQLDocs.build(path: 'location/to/sw-api.json')
Breakdown
There are several phases going on in one little GraphQLDocs.build
call:
- The GraphQL JSON is fetched (if you passed
url
) throughGraphQL::Client
(or simply read if you passedpath
). GraphQL::Parser
manipulates that JSON into a slightly saner format.GraphQL::Generator
takes that JSON and converts it into HTML.GraphQL::Renderer
technically runs as part of the generation phase. It passes the contents of each page through a Markdown renderer.
If you wanted to, you could break these calls up individually. For example:
options = {}
options[:path] = "#{File.dirname(__FILE__)}/../data/graphql/docs.json"
my_renderer = MySuperCoolRenderer(options)
options[:renderer] = my_renderer
options = GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge(options)
response = File.read(options[:path])
parser = GraphQLDocs::Parser.new(response, options)
parsed_schema = parser.parse
generator = GraphQLDocs::Generator.new(parsed_schema, options)
generator.generate
Generating output
By default, the HTML generation process uses ERB to layout the content. There are a bunch of default options provided for you, but feel free to override any of these. The Configuration section below has more information on what you can change.
It also uses html-pipeline to perform the Markdown rendering by default. You can override this by providing a custom rendering class. initialize
takes two arguments, the configuration options and the parsed schema. You must implement at least one method, render
, which takes the GraphQL type, the name, and the layout contents. For example:
class CustomRenderer
def initialize(options, parsed_schema)
@options = options
@parsed_schema = parsed_schema
end
def render(type, name, contents)
contents.sub(/Repository/i, 'Meow Woof!')
end
end
options[:path] = 'location/to/sw-api.json'
options[:renderer] = CustomRenderer
GraphQLDocs.build(options)
Helper methods
In your ERB layouts, there are several helper methods you can use. The helper methods are:
slugify(str)
- This slugifies the given string.include(filename, opts)
- This embeds a template from yourincludes
folder, passing along the local options provided.markdown(string)
- This converts a string from Markdown to HTML.format_type(field)
- This formats a type into an IDL-like representation. For example:!Blah
or[!Foo]
.graphql_mutation_types
,graphql_object_types
,graphql_interface_types
,graphql_enum_types
,graphql_union_types
,graphql_input_object_types
,graphql_scalar_types
- Collections of the various GraphQL types.
To call these methods within templates, you must use the dot notation, such as <%= slugify.(text) %>
.
Configuration
The following options are available:
Option | Description | Default |
---|---|---|
access_token |
Uses this token while making requests through GraphQLDocs::Client . |
nil |
headers |
Uses these headers while making requests through GraphQLDocs::Client . |
{} |
login |
Uses this login while making requests through GraphQLDocs::Client . |
nil |
password |
Uses this password while making requests through GraphQLDocs::Client . |
nil |
path |
GraphQLDocs::Client loads a JSON file found at this location, representing the response from an introspection query. |
nil |
url |
GraphQLDocs::Client makes a POST request to this URL, passing along the introspection query. |
nil |
output_dir |
The location of the output HTML. | ./output/ |
use_default_styles |
Indicates if you want to use the default styles. | true |
base_url |
Indicates the base URL to prepend for assets and links. | true |
delete_output |
Deletes output_dir before generating content. |
false |
pipeline_config |
Defines two sub-keys, pipeline and context , which are used by html-pipeline when rendering your output. |
pipeline has ExtendedMarkdownFilter , EmojiFilter , and TableOfContentsFilter . context has gfm: false and asset_root set to GitHub's CDN. |
renderer |
The rendering class to use. | GraphQLDocs::Renderer |
templates |
The templates to use when generating HTML. You may override any of the following keys: default , includes , objects , mutations , interfaces , enums , unions , input_objects , scalars . |
The defaults are found in lib/graphql-docs/layouts/. |
landing_pages |
The landing page to use when generating HTML for each type. You may override any of the following keys: index , query , object , mutation , interface , enum , union , input_object , scalar . |
The defaults are found in lib/graphql-docs/layouts/. |
classes |
Additional class names you can provide to certain elements. | The full list is found in lib/graphql-docs/configuration.rb/. |
Development
After checking out the repo, run script/bootstrap
to install dependencies. Then, run rake test
to run the tests. You can also run bundle exec rake console
for an interactive prompt that will allow you to experiment.
Sample site
Clone this repository and run:
bundle exec rake sample
to see some sample output.