Easily generate beautiful documentation from your GraphQL schema.
Add this line to your application's Gemfile:
gem 'graphql-docs'
And then execute:
$ bundle
Or install it yourself as:
$ gem install graphql-docs
# pass in a filename
GraphQLDocs.build(filename: filename)
# or pass in a string
GraphQLDocs.build(schema: contents)
# or a schema class
schema = GraphQL::Schema.define do
query query_type
end
GraphQLDocs.build(schema: schema)
There are several phases going on the single GraphQLDocs.build
call:
- The GraphQL IDL file is read (if you passed
filename
) throughGraphQL::Client
(or simply read if you passed a string throughschema
). GraphQL::Parser
manipulates the IDL into a slightly saner format.GraphQL::Generator
takes that saner format and begins the process of applying items to the HTML templates.GraphQL::Renderer
technically runs as part of the generation phase. It passes the contents of each page and converts it into HTML.
If you wanted to, you could break these calls up individually. For example:
options = {}
options[:filename] = "#{File.dirname(__FILE__)}/../data/graphql/schema.idl"
options[:renderer] = MySuperCoolRenderer
options = GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge(options)
response = File.read(options[:filename])
parser = GraphQLDocs::Parser.new(response, options)
parsed_schema = parser.parse
generator = GraphQLDocs::Generator.new(parsed_schema, options)
generator.generate
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 rendering by default. You can override this by providing a custom rendering class.You must implement two methods:
initialize
- Takes two arguments, the parsedschema
and the configurationoptions
.render
Takes the contents of a template page. It also takes two optional kwargs, the GraphQLtype
and itsname
. For example:
class CustomRenderer
def initialize(parsed_schema, options)
@parsed_schema = parsed_schema
@options = options
end
def render(contents, type: nil, name: nil)
contents.sub(/Repository/i, '<strong>Meow Woof!</strong>')
opts[:content] = contents
@graphql_default_layout.result(OpenStruct.new(opts).instance_eval { binding })
end
end
options[:filename] = 'location/to/sw-api.graphql'
options[:renderer] = CustomRenderer
GraphQLDocs.build(options)
If your render
method returns nil
, the Generator
will not attempt to write any HTML file.
The layouts for the individual GraphQL pages are ERB templates, but you can also use ERB templates for your static landing pages.
If you want to add additional variables for your landing pages, you can add define a variables
hash within the landing_pages
option.
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.markdownify(string)
- This converts a string into HTML via CommonMarker.graphql_operation_types
,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) %>
.
The following options are available:
Option | Description | Default |
---|---|---|
filename |
The location of your schema's IDL file. | nil |
schema |
A string representing a schema IDL file. | 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. | "" |
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 , operations , 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 available in lib/graphql-docs/configuration.rb. |
notices |
A proc used to add notices to schema members. See Customizing Notices section below. | nil |
A notice is a block of CommonMark text that optionally has a title which is displayed above a schema member's description. The look of a notice block can be controlled by specifying a custom class for it and then styled via CSS.
The notices
option allows you to customize the notices that appear for a specific schema member using a proc.
The proc will be called for each schema member and needs to return an array of notices or an empty array if there are none.
A notice
has the following options:
Option | Description |
---|---|
body |
CommonMark body of the notice |
title |
Optional title of the notice |
class |
Optional CSS class for the wrapper <div> of the notice |
title_class |
Optional CSS class for the <span> of the notice's title |
Example of a notices
proc that adds a notice to the TeamDiscussion
type:
options[:notices] = ->(schema_member_path) {
notices = []
if schema_member_path == "TeamDiscussion"
notices << {
class: "preview-notice",
body: "Available via the [Team Discussion](/previews/team-discussion) preview.",
}
end
notices
}
The format of schema_member_path
is a dot delimited path to the schema member. For example:
"Author", # an object
"ExtraInfo" # an interface,
"Author.socialSecurityNumber" # a field
"Book.author.includeMiddleInitial" # an argument
"Likeable" # a union,
"Cover" # an enum
"Cover.DIGITAL" # an enum value
"BookOrder" # an input object
"Mutation.addLike" # a mutation
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.
Clone this repository and run:
bundle exec rake sample
to see some sample output.