Module: GraphQLDocs

Defined in:
lib/graphql-docs.rb,
lib/graphql-docs/parser.rb,
lib/graphql-docs/helpers.rb,
lib/graphql-docs/version.rb,
lib/graphql-docs/renderer.rb,
lib/graphql-docs/generator.rb,
lib/graphql-docs/configuration.rb

Overview

GraphQLDocs is a library for generating beautiful HTML documentation from GraphQL schemas. It parses GraphQL schema files or schema objects and generates a complete documentation website with customizable templates and styling.

Examples:

Generate docs from a file

GraphQLDocs.build(filename: 'schema.graphql')

Generate docs from a schema string

GraphQLDocs.build(schema: schema_string)

Generate docs from a schema class

schema = GraphQL::Schema.define { query query_type }
GraphQLDocs.build(schema: schema)

See Also:

Defined Under Namespace

Modules: Configuration, Helpers Classes: Generator, Parser, Renderer

Constant Summary collapse

VERSION =

Current version of the GraphQLDocs gem

'5.2.0'

Class Method Summary collapse

Class Method Details

.build(options) ⇒ Boolean

Builds HTML documentation from a GraphQL schema.

This is the main entry point for generating documentation. It accepts either a schema file path or a schema string/object, parses it, and generates a complete HTML documentation website.

Examples:

Basic usage with file

GraphQLDocs.build(filename: 'schema.graphql')

With custom options

GraphQLDocs.build(
  filename: 'schema.graphql',
  output_dir: './docs',
  base_url: '/api-docs',
  delete_output: true
)

With custom renderer

class MyRenderer < GraphQLDocs::Renderer
  def render(contents, type: nil, name: nil)
    # Custom rendering logic
  end
end
GraphQLDocs.build(filename: 'schema.graphql', renderer: MyRenderer)

Parameters:

  • options (Hash) —

    Configuration options for generating the documentation

Options Hash (options):

  • :filename (String) —

    Path to GraphQL schema IDL file

  • :schema (String, GraphQL::Schema) —

    GraphQL schema as string or schema class

  • :output_dir (String) — default: './output/' —

    Directory where HTML will be generated

  • :use_default_styles (Boolean) — default: true —

    Whether to include default CSS styles

  • :base_url (String) — default: '' —

    Base URL to prepend for assets and links

  • :delete_output (Boolean) — default: false —

    Delete output directory before generating

  • :pipeline_config (Hash) —

    Configuration for html-pipeline rendering

  • :renderer (Class) — default: GraphQLDocs::Renderer —

    Custom renderer class

  • :templates (Hash) —

    Custom template file paths

  • :landing_pages (Hash) —

    Custom landing page file paths

  • :classes (Hash) —

    Additional CSS class names for elements

  • :notices (Proc) —

    Proc for adding notices to schema members

Returns:

  • (Boolean) —

    Returns true on successful generation

Raises:

  • (ArgumentError) —

    If both filename and schema are provided, or if neither is provided

  • (ArgumentError) —

    If the specified filename does not exist

  • (TypeError) —

    If filename is not a String

  • (TypeError) —

    If schema is not a String or GraphQL::Schema

See Also:



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/graphql-docs.rb', line 73

def build(options)
  # do not let user provided values overwrite every single value
  %i[templates landing_pages].each do |opt|
    next unless options.key?(opt)

    GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS[opt].each_pair do |key, value|
      options[opt][key] = value unless options[opt].key?(key)
    end
  end

  options = GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge(options)

  filename = options[:filename]
  schema = options[:schema]

  raise ArgumentError, 'Pass in `filename` or `schema`, but not both!' if !filename.nil? && !schema.nil?

  raise ArgumentError, 'Pass in either `filename` or `schema`' if filename.nil? && schema.nil?

  if filename
    raise TypeError, "Expected `String`, got `#{filename.class}`" unless filename.is_a?(String)

    raise ArgumentError, "#{filename} does not exist!" unless File.exist?(filename)

    schema = File.read(filename)
  else
    raise TypeError, "Expected `String` or `GraphQL::Schema`, got `#{schema.class}`" if !schema.is_a?(String) && !schema_type?(schema)

    schema = schema
  end

  parser = GraphQLDocs::Parser.new(schema, options)
  parsed_schema = parser.parse

  generator = GraphQLDocs::Generator.new(parsed_schema, options)

  generator.generate
end