82 |
103 |
104 |
105 |
106 |
--------------------------------------------------------------------------------
/lib/graphql-docs/layouts/graphql_directives.html:
--------------------------------------------------------------------------------
1 |
83 |
84 |
87 |
88 |
89 | <%= contents %>
90 |
91 |
92 |
93 |
94 |
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 | <%= type[:name] %>
2 | 3 | <%= include.('notices.html', notices: type[:notices]) %> 4 | 5 | <%= type[:description] %> 6 | 7 | <%= include.('locations.html', locations: type[:locations]) %> 8 | 9 | <% unless type[:arguments].empty? %> 10 | 11 |Arguments
12 | 13 | <%= include.('arguments.html', arguments: type[:arguments]) %> 14 | 15 | <% end %> 16 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_enums.html: -------------------------------------------------------------------------------- 1 |<%= type[:name] %>
2 | 3 | <%= include.('notices.html', notices: type[:notices]) %> 4 | 5 | <%= type[:description] %> 6 | 7 | <%= include.('values.html', values: type[:values]) %> 8 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_input_objects.html: -------------------------------------------------------------------------------- 1 |<%= type[:name] %>
2 | 3 | <%= include.('notices.html', notices: type[:notices]) %> 4 | 5 | <%= type[:description] %> 6 | 7 | <% unless type[:input_fields].nil? %> 8 | 9 |Input Fields
10 | 11 | <%= include.('input_fields.html', input_fields: type[:input_fields]) %> 12 | 13 | <% end %> 14 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_interfaces.html: -------------------------------------------------------------------------------- 1 |<%= type[:name] %>
2 | 3 | <%= include.('notices.html', notices: type[:notices]) %> 4 | 5 | <%= type[:description] %> 6 | 7 | <% unless type[:implemented_by].empty? %> 8 | 9 |Implemented by
10 | 11 |-
12 | <% type[:implemented_by].each do |implementor| %>
13 |
<%= implementor %>
14 | <% end %>
15 |
Fields
22 | 23 | <%= include.('fields.html', fields: type[:fields]) %> 24 | 25 | <% end %> 26 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_mutations.html: -------------------------------------------------------------------------------- 1 |<%= type[:name] %>
2 | 3 | <%= include.('notices.html', notices: type[:notices]) %> 4 | 5 | <%= type[:description] %> 6 | 7 | <% if !type[:input_fields].empty? %> 8 | 9 |Input fields
10 | 11 | <%= include.('fields.html', fields: type[:input_fields]) %> 12 | 13 | <% end %> 14 | 15 | 16 | <% if !type[:return_fields].empty? %> 17 | 18 |Return fields
19 | 20 | <%= include.('fields.html', fields: type[:return_fields]) %> 21 | 22 | <% end %> 23 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_objects.html: -------------------------------------------------------------------------------- 1 |<%= type[:name] %>
2 | 3 | <%= include.('notices.html', notices: type[:notices]) %> 4 | 5 | <%= type[:description] %> 6 | 7 | <% unless type[:interfaces].empty? %> 8 | 9 |Implements
10 | 11 |-
12 | <% type[:interfaces].each do |interface| %>
13 |
<%= interface %>
14 | <% end %>
15 |
Connections
22 | 23 | <%= include.('connections.html', connections: type[:connections]) %> 24 | 25 | <% end %> 26 | 27 | <% unless type[:fields].empty? %> 28 | 29 |Fields
30 | 31 | <%= include.('fields.html', fields: type[:fields]) %> 32 | 33 | <% end %> 34 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_operations.html: -------------------------------------------------------------------------------- 1 |<%= type[:name] %>
2 | 3 | <%= type[:description] %> 4 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_queries.html: -------------------------------------------------------------------------------- 1 |<%= type[:name] %>
2 | 3 | <%= include.('notices.html', notices: type[:notices]) %> 4 | 5 | <%= type[:description] %> 6 | 7 | <% if !type[:arguments].empty? %> 8 | 9 |Arguments
10 | 11 | <%= include.('fields.html', fields: type[:arguments]) %> 12 | 13 | <% end %> 14 | 15 | 16 | <% if !type[:return_fields].empty? %> 17 | 18 |Return fields
19 | 20 | <%= include.('fields.html', fields: type[:return_fields]) %> 21 | 22 | <% end %> 23 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_scalars.html: -------------------------------------------------------------------------------- 1 | # <%= type[:name] %> 2 | 3 | <%= type[:description] %> 4 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/graphql_unions.html: -------------------------------------------------------------------------------- 1 |<%= type[:name] %>
2 | 3 | <%= include.('notices.html', notices: type[:notices]) %> 4 | 5 | <%= type[:description] %> 6 | 7 | <%= include.('possible_types.html', possible_types: type[:possible_types]) %> 8 | -------------------------------------------------------------------------------- /lib/graphql-docs/layouts/includes/arguments.html: -------------------------------------------------------------------------------- 1 || Argument | 5 |Type | 6 |Description | 7 |
|---|---|---|
<%= argument[:name] %> |
13 |
14 | <%= argument[:type][:info] %>
15 | |
16 |
17 | <%= markdownify.(argument[:description]) %>
18 | <% unless (default_value = argument[:default_value]).nil? %>
19 | The default value is |
22 |
4 | <%= connection[:name] %> (
18 |
19 | <% end %>
20 |
--------------------------------------------------------------------------------
/lib/graphql-docs/layouts/includes/deprecations.html:
--------------------------------------------------------------------------------
1 | <% if item[:is_deprecated] %>
2 | <%= connection[:type][:info] %>)
5 |
6 |
7 | <%= include.('deprecations.html', item: connection) %>
8 |
9 | <%= include.('notices.html', notices: connection[:notices]) %>
10 |
11 | <%= markdownify.(connection[:description]) %>
12 |
13 | <% unless connection[:arguments].empty? %>
14 | <%= include.('arguments.html', arguments: connection[:arguments]) %>
15 | <% end %>
16 |
17 |
3 | Deprecation notice
4 | <%= markdownify.(item[:deprecation_reason]) %>
5 |
6 | <% end %>
7 |
--------------------------------------------------------------------------------
/lib/graphql-docs/layouts/includes/fields.html:
--------------------------------------------------------------------------------
1 | <% fields.each do |field| %>
2 |
3 |
4 | <%= field[:name] %> (
18 |
19 | <% end %>
20 |
--------------------------------------------------------------------------------
/lib/graphql-docs/layouts/includes/input_fields.html:
--------------------------------------------------------------------------------
1 | <% input_fields.each do |field| %>
2 |
3 | <%= field[:type][:info] %>)
5 |
6 |
7 | <%= include.('deprecations.html', item: field) %>
8 |
9 | <%= include.('notices.html', notices: field[:notices]) %>
10 |
11 | <%= markdownify.(field[:description]) %>
12 |
13 | <% unless field[:arguments].empty? %>
14 | <%= include.('arguments.html', arguments: field[:arguments]) %>
15 | <% end %>
16 |
17 |
4 | <%= field[:name] %> (
16 |
17 | <% end %>
18 |
--------------------------------------------------------------------------------
/lib/graphql-docs/layouts/includes/locations.html:
--------------------------------------------------------------------------------
1 | <%= field[:type][:info] %>)
5 |
6 |
7 | <%= include.('notices.html', notices: field[:notices]) %>
8 |
9 | <%= markdownify.(field[:description]) %>
10 |
11 | <% unless field[:arguments].empty? %>
12 | <%= include.('arguments.html', arguments: field[:arguments]) %>
13 | <% end %>
14 |
15 | Locations
2 | 3 |-
4 |
5 | <% locations.each do |location| %>
6 |
- <%= location %> 7 | <% end %> 8 | 9 |
3 | <% if notice[:title] %>
4 | <%= notice[:title] %>
5 | <% end %>
6 | <%= markdownify.(notice[:body]) %>
7 |
8 | <% end %>
9 |
--------------------------------------------------------------------------------
/lib/graphql-docs/layouts/includes/possible_types.html:
--------------------------------------------------------------------------------
1 | Possible Types
2 | 3 |-
4 |
5 | <% possible_types.each do |possible_type| %>
6 |
- <%= possible_type %> 7 | <% end %> 8 | 9 |
2 | 
3 |
4 |
5 |
3 |
4 | -
6 |
- 7 | 11 | 12 | 13 |
-
14 |
Operations
15 | 27 |
28 |
29 | - 30 | 31 | 41 | 42 | 43 |
- 44 | 45 | 55 | 56 | 57 |
- 58 | 59 | 69 | 70 | 71 |
- 72 | 73 | 83 | 84 | 85 |
- 86 | 87 | 97 | 98 | 99 |
- 100 | 101 | 111 | 112 | 113 |
- 114 | 115 | 125 | 126 | 127 |
- 128 | 129 | 139 | 140 | 141 |
- 142 | 143 | 153 | 154 |
Values
2 | 3 | <% values.each do |value| %> 4 | 5 |<%= value[:name] %>
6 | 7 |
8 | <%= include.('deprecations.html', item: value) %>
9 |
10 | <%= include.('notices.html', notices: value[:notices]) %>
11 |
12 | <%= markdownify.(value[:description]) %>
13 |
14 |
15 | <% end %>
16 |
--------------------------------------------------------------------------------
/lib/graphql-docs/parser.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | require 'graphql'
4 |
5 | module GraphQLDocs
6 | class Parser
7 | include Helpers
8 |
9 | attr_reader :processed_schema
10 |
11 | def initialize(schema, options)
12 | @options = options
13 |
14 | @options[:notices] ||= ->(_schema_member_path) { [] }
15 |
16 | @schema = if schema.is_a?(String)
17 | GraphQL::Schema.from_definition(schema)
18 | elsif schema < GraphQL::Schema
19 | schema
20 | end
21 |
22 | @processed_schema = {
23 | operation_types: [],
24 | query_types: [],
25 | mutation_types: [],
26 | object_types: [],
27 | interface_types: [],
28 | enum_types: [],
29 | union_types: [],
30 | input_object_types: [],
31 | scalar_types: [],
32 | directive_types: []
33 | }
34 | end
35 |
36 | def parse
37 | root_types = {}
38 | %w[query mutation].each do |operation|
39 | root_types[operation] = @schema.root_type_for_operation(operation).graphql_name unless @schema.root_type_for_operation(operation).nil?
40 | end
41 | @processed_schema[:root_types] = root_types
42 |
43 | @schema.types.each_value do |object|
44 | data = {}
45 |
46 | data[:notices] = @options[:notices].call(object.graphql_name)
47 |
48 | if object < ::GraphQL::Schema::Object
49 | data[:name] = object.graphql_name
50 | data[:description] = object.description
51 |
52 | if data[:name] == root_types['query']
53 | data[:interfaces] = object.interfaces.map(&:graphql_name).sort
54 | data[:fields], data[:connections] = fetch_fields(object.fields, object.graphql_name)
55 | @processed_schema[:operation_types] << data
56 |
57 | object.fields.each_value do |query|
58 | h = {}
59 |
60 | h[:notices] = @options[:notices].call([object.graphql_name, query.graphql_name].join('.'))
61 | h[:name] = query.graphql_name
62 | h[:description] = query.description
63 | h[:arguments], = fetch_fields(query.arguments, [object.graphql_name, query.graphql_name].join('.'))
64 |
65 | return_type = query.type
66 | if return_type.unwrap.respond_to?(:fields)
67 | h[:return_fields], = fetch_fields(return_type.unwrap.fields, return_type.graphql_name)
68 | else # it is a scalar return type
69 | h[:return_fields], = fetch_fields({ return_type.graphql_name => query }, return_type.graphql_name)
70 | end
71 |
72 | @processed_schema[:query_types] << h
73 | end
74 | elsif data[:name] == root_types['mutation']
75 | @processed_schema[:operation_types] << data
76 |
77 | object.fields.each_value do |mutation|
78 | h = {}
79 |
80 | h[:notices] = @options[:notices].call([object.graphql_name, mutation.graphql_name].join('.'))
81 | h[:name] = mutation.graphql_name
82 | h[:description] = mutation.description
83 | h[:input_fields], = fetch_fields(mutation.arguments, [object.graphql_name, mutation.graphql_name].join('.'))
84 |
85 | return_type = mutation.type
86 | if return_type.unwrap.respond_to?(:fields)
87 | h[:return_fields], = fetch_fields(return_type.unwrap.fields, return_type.graphql_name)
88 | else # it is a scalar return type
89 | h[:return_fields], = fetch_fields({ return_type.graphql_name => mutation }, return_type.graphql_name)
90 | end
91 |
92 | @processed_schema[:mutation_types] << h
93 | end
94 | else
95 | data[:interfaces] = object.interfaces.map(&:graphql_name).sort
96 | data[:fields], data[:connections] = fetch_fields(object.fields, object.graphql_name)
97 |
98 | @processed_schema[:object_types] << data
99 | end
100 | elsif object < ::GraphQL::Schema::Interface
101 | data[:name] = object.graphql_name
102 | data[:description] = object.description
103 | data[:fields], data[:connections] = fetch_fields(object.fields, object.graphql_name)
104 |
105 | @processed_schema[:interface_types] << data
106 | elsif object < ::GraphQL::Schema::Enum
107 | data[:name] = object.graphql_name
108 | data[:description] = object.description
109 |
110 | data[:values] = object.values.values.map do |val|
111 | h = {}
112 | h[:notices] = @options[:notices].call([object.graphql_name, val.graphql_name].join('.'))
113 | h[:name] = val.graphql_name
114 | h[:description] = val.description
115 | unless val.deprecation_reason.nil?
116 | h[:is_deprecated] = true
117 | h[:deprecation_reason] = val.deprecation_reason
118 | end
119 | h
120 | end
121 |
122 | @processed_schema[:enum_types] << data
123 | elsif object < ::GraphQL::Schema::Union
124 | data[:name] = object.graphql_name
125 | data[:description] = object.description
126 | data[:possible_types] = object.possible_types.map(&:graphql_name).sort
127 |
128 | @processed_schema[:union_types] << data
129 | elsif object < GraphQL::Schema::InputObject
130 | data[:name] = object.graphql_name
131 | data[:description] = object.description
132 |
133 | data[:input_fields], = fetch_fields(object.arguments, object.graphql_name)
134 |
135 | @processed_schema[:input_object_types] << data
136 | elsif object < GraphQL::Schema::Scalar
137 | data[:name] = object.graphql_name
138 | data[:description] = object.description
139 |
140 | @processed_schema[:scalar_types] << data
141 | else
142 | raise TypeError, "I'm not sure what #{object.class} < #{object.superclass.name} is!"
143 | end
144 | end
145 |
146 | @schema.directives.each_value do |directive|
147 | data = {}
148 | data[:notices] = @options[:notices].call(directive.graphql_name)
149 |
150 | data[:name] = directive.graphql_name
151 | data[:description] = directive.description
152 | data[:locations] = directive.locations
153 |
154 | data[:arguments], = fetch_fields(directive.arguments, directive.graphql_name)
155 |
156 | @processed_schema[:directive_types] << data
157 | end
158 |
159 | sort_by_name!
160 |
161 | @processed_schema[:interface_types].each do |interface|
162 | interface[:implemented_by] = []
163 | @processed_schema[:object_types].each do |obj|
164 | interface[:implemented_by] << obj[:name] if obj[:interfaces].include?(interface[:name])
165 | end
166 | end
167 |
168 | @processed_schema
169 | end
170 |
171 | private
172 |
173 | def fetch_fields(object_fields, parent_path)
174 | fields = []
175 | connections = []
176 |
177 | object_fields.each_value do |field|
178 | hash = {}
179 |
180 | hash[:notices] = @options[:notices].call([parent_path, field.graphql_name].join('.'))
181 | hash[:name] = field.graphql_name
182 | hash[:description] = field.description
183 | if field.respond_to?(:deprecation_reason) && !field.deprecation_reason.nil?
184 | hash[:is_deprecated] = true
185 | hash[:deprecation_reason] = field.deprecation_reason
186 | end
187 |
188 | hash[:type] = generate_type(field.type)
189 |
190 | hash[:arguments] = []
191 | if field.respond_to?(:arguments)
192 | field.arguments.each_value do |arg|
193 | h = {}
194 | h[:name] = arg.graphql_name
195 | h[:description] = arg.description
196 | h[:type] = generate_type(arg.type)
197 | h[:default_value] = arg.default_value if arg.default_value?
198 | if arg.respond_to?(:deprecation_reason) && arg.deprecation_reason
199 | h[:is_deprecated] = true
200 | h[:deprecation_reason] = arg.deprecation_reason
201 | end
202 | hash[:arguments] << h
203 | end
204 | end
205 |
206 | if !argument?(field) && connection?(field)
207 | connections << hash
208 | else
209 | fields << hash
210 | end
211 | end
212 |
213 | [fields, connections]
214 | end
215 |
216 | def generate_type(type)
217 | name = type.unwrap.graphql_name
218 |
219 | path = if type.unwrap < GraphQL::Schema::Object
220 | if name == 'Query'
221 | 'operation'
222 | else
223 | 'object'
224 | end
225 | elsif type.unwrap < GraphQL::Schema::Scalar
226 | 'scalar'
227 | elsif type.unwrap < GraphQL::Schema::Interface
228 | 'interface'
229 | elsif type.unwrap < GraphQL::Schema::Enum
230 | 'enum'
231 | elsif type.unwrap < GraphQL::Schema::InputObject
232 | 'input_object'
233 | elsif type.unwrap < GraphQL::Schema::Union
234 | 'union'
235 | else
236 | raise TypeError, "Unknown type for `#{name}`: `#{type.unwrap.class}`"
237 | end
238 |
239 | {
240 | name: name,
241 | path: "#{path}/#{slugify(name)}",
242 | info: type.to_type_signature
243 | }
244 | end
245 |
246 | def argument?(field)
247 | field.is_a?(::GraphQL::Schema::Argument)
248 | end
249 |
250 | def connection?(field)
251 | field.respond_to?(:connection?) && field.connection?
252 | end
253 |
254 | def sort_by_name!
255 | @processed_schema.each_pair do |key, value|
256 | next if value.empty?
257 | next if %i[operation_types root_types].include?(key)
258 |
259 | value.sort_by! { |o| o[:name] }
260 | end
261 | end
262 | end
263 | end
264 |
--------------------------------------------------------------------------------
/lib/graphql-docs/renderer.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | require 'html/pipeline'
4 | require 'yaml'
5 | require 'extended-markdown-filter'
6 | require 'ostruct'
7 |
8 | module GraphQLDocs
9 | class Renderer
10 | include Helpers
11 |
12 | attr_reader :options
13 |
14 | def initialize(parsed_schema, options)
15 | @parsed_schema = parsed_schema
16 | @options = options
17 |
18 | @graphql_default_layout = ERB.new(File.read(@options[:templates][:default])) unless @options[:templates][:default].nil?
19 |
20 | @pipeline_config = @options[:pipeline_config] || {}
21 | pipeline = @pipeline_config[:pipeline] || {}
22 | context = @pipeline_config[:context] || {}
23 |
24 | filters = pipeline.map do |f|
25 | if filter?(f)
26 | f
27 | else
28 | key = filter_key(f)
29 | filter = HTML::Pipeline.constants.find { |c| c.downcase == key }
30 | # possibly a custom filter
31 | if filter.nil?
32 | Kernel.const_get(f)
33 | else
34 | HTML::Pipeline.const_get(filter)
35 | end
36 | end
37 | end
38 |
39 | @pipeline = HTML::Pipeline.new(filters, context)
40 | end
41 |
42 | def render(contents, type: nil, name: nil, filename: nil)
43 | opts = { base_url: @options[:base_url], output_dir: @options[:output_dir] }.merge({ type: type, name: name, filename: filename }).merge(helper_methods)
44 |
45 | contents = to_html(contents, context: { filename: filename })
46 | return contents if @graphql_default_layout.nil?
47 |
48 | opts[:content] = contents
49 | @graphql_default_layout.result(OpenStruct.new(opts).instance_eval { binding })
50 | end
51 |
52 | def to_html(string, context: {})
53 | @pipeline.to_html(string, context)
54 | end
55 |
56 | private
57 |
58 | def filter_key(str)
59 | str.downcase
60 | end
61 |
62 | def filter?(filter)
63 | filter < HTML::Pipeline::Filter
64 | rescue LoadError, ArgumentError
65 | false
66 | end
67 | end
68 | end
69 |
--------------------------------------------------------------------------------
/lib/graphql-docs/version.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | module GraphQLDocs
4 | VERSION = '5.2.0'
5 | end
6 |
--------------------------------------------------------------------------------
/test/cli_test.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | require 'test_helper'
4 |
5 | class CliTest < Minitest::Test
6 | def setup
7 | @schema = File.join(fixtures_dir, 'sw-schema.graphql')
8 | end
9 |
10 | def test_cli_works
11 | FileUtils.rm_rf("output")
12 | assert cmd("#{@schema}")
13 | assert File.exist?(File.join("output", 'index.html'))
14 | end
15 |
16 | def test_cli_works_with_output_dir
17 | clean_up_output # NOTE: this is the fixture output dir
18 | schema = File.join(fixtures_dir, 'sw-schema.graphql')
19 | assert cmd("#{@schema} -o #{output_dir}")
20 | assert File.exist?(File.join(output_dir, 'index.html'))
21 | end
22 |
23 | def test_cli_requires_schema
24 | _out, err = capture_subprocess_io do
25 | refute cmd("", exception: false)
26 | end
27 | assert_match /schema must be specified/, err
28 | end
29 |
30 | def test_cli_help
31 | out, err = capture_subprocess_io do
32 | assert cmd("--help")
33 | end
34 | assert_match /Usage/, out
35 | assert err.empty?, "errors not empty: #{err}"
36 | end
37 |
38 | def test_cli_verbose
39 | out, err = capture_subprocess_io do
40 | assert cmd("#{@schema} --verbose")
41 | end
42 | assert_match /Generating site/, out
43 | assert_match /Site successfully generated/, out
44 | assert err.empty?, "errors not empty: #{err}"
45 | end
46 |
47 | def test_cli_base_url
48 | out, err = capture_subprocess_io do
49 | assert cmd("#{@schema} -b https://example.com")
50 | end
51 | assert err.empty?, "errors not empty: #{err}"
52 | assert File.read(File.join("output", 'index.html')).include?("")
53 | end
54 |
55 | def test_cli_version
56 | out, err = capture_subprocess_io do
57 | assert cmd("--version")
58 | end
59 | assert_match /#{GraphQLDocs::VERSION}/, out
60 | assert err.empty?, "errors not empty: #{err}"
61 | end
62 |
63 | private
64 |
65 | def cmd(args, exception: true)
66 | system("ruby -Ilib ./exe/graphql-docs #{args}", exception: exception)
67 | end
68 | end
69 |
--------------------------------------------------------------------------------
/test/graphql-docs/fixtures/landing_pages/broken_yaml.md:
--------------------------------------------------------------------------------
1 | ---
2 | hey now
3 | ---
4 |
5 | # Words, words
6 |
--------------------------------------------------------------------------------
/test/graphql-docs/fixtures/landing_pages/object.erb:
--------------------------------------------------------------------------------
1 | ---
2 | title: Variable Objects
3 | ---
4 | # Objects
5 |
6 | <%= some_var %> in GraphQL represent the resources that you can access.
7 |
--------------------------------------------------------------------------------
/test/graphql-docs/fixtures/landing_pages/whitespace_template.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: GraphQL documentation
3 | ---
4 |
5 | # GraphQL Reference
6 |
7 | ```json
8 | {
9 | "nest1": {
10 | "nest2": {
11 | "nest3": true
12 | }
13 | }
14 | }
15 | ```
16 |
--------------------------------------------------------------------------------
/test/graphql-docs/fixtures/sw-schema.graphql:
--------------------------------------------------------------------------------
1 | """
2 | A character in the Star Wars Trilogy
3 | """
4 | interface Character {
5 | """
6 | Which movies they appear in.
7 | """
8 | appearsIn: [Episode]
9 |
10 | """
11 | The friends of the character, or an empty list if they have none.
12 | """
13 | friends: [Character]
14 |
15 | """
16 | The id of the character.
17 | """
18 | id: ID!
19 |
20 | """
21 | The name of the character.
22 | """
23 | name: String
24 |
25 | """
26 | All secrets about their past.
27 | """
28 | secretBackstory: String
29 | }
30 |
31 | """
32 | A mechanical creature in the Star Wars universe.
33 | """
34 | type Droid implements Character {
35 | """
36 | Which movies they appear in.
37 | """
38 | appearsIn: [Episode]
39 |
40 | """
41 | The friends of the droid, or an empty list if they have none.
42 | """
43 | friends: [Character]
44 |
45 | """
46 | The id of the droid.
47 | """
48 | id: ID!
49 |
50 | """
51 | The name of the droid.
52 | """
53 | name: String
54 |
55 | """
56 | The primary function of the droid.
57 | """
58 | primaryFunction: String
59 |
60 | """
61 | Construction date and the name of the designer.
62 | """
63 | secretBackstory: String
64 | }
65 |
66 | """
67 | One of the films in the Star Wars Trilogy
68 | """
69 | enum Episode {
70 | """
71 | Released in 1980.
72 | """
73 | EMPIRE
74 |
75 | """
76 | Released in 1983.
77 | """
78 | JEDI
79 |
80 | """
81 | Released in 1977.
82 | """
83 | NEWHOPE
84 | }
85 |
86 | """
87 | A humanoid creature in the Star Wars universe.
88 | """
89 | type Human implements Character {
90 | """
91 | Which movies they appear in.
92 | """
93 | appearsIn: [Episode]
94 |
95 | """
96 | The friends of the human, or an empty list if they have none.
97 | """
98 | friends: [Character]
99 |
100 | """
101 | The home planet of the human, or null if unknown.
102 | """
103 | homePlanet: String
104 |
105 | """
106 | The id of the human.
107 | """
108 | id: ID!
109 |
110 | """
111 | The name of the human.
112 | """
113 | name: String
114 |
115 | """
116 | Where are they from and how they came to be who they are.
117 | """
118 | secretBackstory: String
119 | }
120 |
121 | """
122 | Root query
123 | """
124 | type Query {
125 | """
126 | Return the Droid by ID.
127 | """
128 | droid(
129 | """
130 | id of the droid
131 | """
132 | id: ID!
133 | ): Droid
134 |
135 | """
136 | Return the hero by episode.
137 | """
138 | hero(
139 | """
140 | If omitted, returns the hero of the whole saga. If provided, returns the hero of that particular episode.
141 | """
142 | episode: Episode
143 | ): Character
144 |
145 | """
146 | Return the Human by ID.
147 | """
148 | human(
149 | """
150 | id of the human
151 | """
152 | id: ID!
153 | ): Human
154 | }
155 |
--------------------------------------------------------------------------------
/test/graphql-docs/fixtures/tiny-schema.graphql:
--------------------------------------------------------------------------------
1 | """
2 | The Code of Conduct for a repository
3 | """
4 | type CodeOfConduct {
5 | """
6 | The body of the CoC
7 | """
8 | body: String
9 |
10 | """
11 | The key for the CoC
12 | """
13 | key: String!
14 |
15 | """
16 | The formal name of the CoC
17 | """
18 | name: String!
19 |
20 | """
21 | The path to the CoC
22 | """
23 | url: URI
24 | }
25 |
26 | """
27 | The query root of GitHub's GraphQL interface.
28 | """
29 | type Query {
30 | """
31 | Look up a code of conduct by its key
32 | """
33 | codeOfConduct(
34 | """
35 | The code of conduct's key
36 | """
37 | key: String!
38 | ): CodeOfConduct
39 | }
40 |
41 | """
42 | An RFC 3986, RFC 3987, and RFC 6570 (level 4) compliant URI string.
43 | """
44 | scalar URI
45 |
--------------------------------------------------------------------------------
/test/graphql-docs/generator_test.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | require 'test_helper'
4 |
5 | class GeneratorTest < Minitest::Test
6 | class CustomRenderer
7 | def initialize(_, _); end
8 |
9 | def render(contents, type: nil, name: nil, filename: nil) # rubocop:disable Lint/UnusedMethodArgument
10 | to_html(contents)
11 | end
12 |
13 | def to_html(contents)
14 | return '' if contents.nil?
15 |
16 | contents.sub(/CodeOfConduct/i, 'CoC!!!!!')
17 | end
18 | end
19 |
20 | def setup
21 | schema = File.read(File.join(fixtures_dir, 'gh-schema.graphql'))
22 | @parser = GraphQLDocs::Parser.new(schema, {})
23 | @results = @parser.parse
24 |
25 | tiny_schema = File.read(File.join(fixtures_dir, 'tiny-schema.graphql'))
26 | @tiny_parser = GraphQLDocs::Parser.new(tiny_schema, {})
27 | @tiny_results = @tiny_parser.parse
28 |
29 | @output_dir = File.join(fixtures_dir, 'output')
30 | end
31 |
32 | def deep_copy(hash)
33 | Marshal.load(Marshal.dump(hash))
34 | end
35 |
36 | def test_that_it_requires_templates
37 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
38 | options[:templates][:objects] = 'BOGUS'
39 |
40 | assert_raises IOError do
41 | GraphQLDocs::Generator.new(@results, options)
42 | end
43 | end
44 |
45 | def test_that_it_does_not_require_default
46 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
47 | options[:templates][:default] = nil
48 |
49 | GraphQLDocs::Generator.new(@results, options)
50 | end
51 |
52 | def test_that_it_works
53 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
54 | options[:output_dir] = @output_dir
55 | options[:delete_output] = true
56 |
57 | generator = GraphQLDocs::Generator.new(@results, options)
58 | generator.generate
59 |
60 | assert File.exist? File.join(@output_dir, 'index.html')
61 | assert File.exist? File.join(@output_dir, 'assets', 'style.css')
62 | assert File.exist? File.join(@output_dir, 'enum', 'issuestate', 'index.html')
63 | assert File.exist? File.join(@output_dir, 'input_object', 'projectorder', 'index.html')
64 | assert File.exist? File.join(@output_dir, 'interface', 'reactable', 'index.html')
65 | assert File.exist? File.join(@output_dir, 'query', 'codeofconduct', 'index.html')
66 | assert File.exist? File.join(@output_dir, 'mutation', 'addcomment', 'index.html')
67 | assert File.exist? File.join(@output_dir, 'object', 'repository', 'index.html')
68 | assert File.exist? File.join(@output_dir, 'scalar', 'boolean', 'index.html')
69 | assert File.exist? File.join(@output_dir, 'union', 'issuetimelineitem', 'index.html')
70 | assert File.exist? File.join(@output_dir, 'directive', 'deprecated', 'index.html')
71 |
72 | # content sanity checks
73 | Dir.glob("#{@output_dir}/**/*.html") do |file|
74 | contents = File.read(file)
75 | # no empty types
76 | refute_match %r{/, object)
134 | end
135 |
136 | def test_that_missing_landing_pages_are_reported
137 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
138 | options[:landing_pages][:index] = 'BOGUS'
139 |
140 | assert_raises IOError do
141 | GraphQLDocs::Generator.new(@tiny_results, options)
142 | end
143 | end
144 |
145 | def test_that_erb_landing_pages_work
146 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
147 | options[:output_dir] = @output_dir
148 | options[:landing_pages][:object] = File.join(fixtures_dir, 'landing_pages', 'object.erb')
149 | options[:landing_pages][:variables] = { some_var: 'wowie!!' }
150 |
151 | generator = GraphQLDocs::Generator.new(@tiny_results, options)
152 | generator.generate
153 |
154 | object = File.read File.join(@output_dir, 'object', 'index.html')
155 |
156 | assert_match(/Variable Objects/, object)
157 | assert_match(/wowie!!/, object)
158 | end
159 |
160 | def test_that_broken_yaml_is_caught
161 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
162 | options[:landing_pages][:index] = File.join(fixtures_dir, 'landing_pages', 'broken_yaml.md')
163 | generator = GraphQLDocs::Generator.new(@tiny_results, options)
164 |
165 | assert_raises TypeError do
166 | generator.generate
167 | end
168 | end
169 |
170 | def test_that_markdown_preserves_whitespace
171 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
172 | options[:output_dir] = @output_dir
173 | options[:landing_pages][:index] = File.join(fixtures_dir, 'landing_pages', 'whitespace_template.md')
174 |
175 | generator = GraphQLDocs::Generator.new(@tiny_results, options)
176 | generator.generate
177 |
178 | contents = File.read File.join(@output_dir, 'index.html')
179 |
180 | assert_match(/ "nest2": \{/, contents)
181 | end
182 |
183 | def test_that_empty_html_lines_not_interpreted_by_markdown
184 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
185 | options[:output_dir] = @output_dir
186 |
187 | generator = GraphQLDocs::Generator.new(@tiny_results, options)
188 | generator.generate
189 |
190 | contents = File.read File.join(@output_dir, 'query', 'codeofconduct', 'index.html')
191 |
192 | assert_match(%r{R2D2 }, contents
16 | end
17 |
18 | def test_that_html_conversion_works
19 | contents = @renderer.to_html('**R2D2**')
20 |
21 | assert_equal '
The code of conduct's key
}, contents) 193 | end 194 | 195 | def test_that_non_empty_html_lines_not_interpreted_by_markdown 196 | options = deep_copy(GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS) 197 | options[:output_dir] = @output_dir 198 | 199 | generator = GraphQLDocs::Generator.new(@results, options) 200 | generator.generate 201 | 202 | contents = File.read File.join(@output_dir, 'input_object', 'projectorder', 'index.html') 203 | 204 | assert_match %r{\n
},
205 | contents
206 | end
207 | end
208 |
--------------------------------------------------------------------------------
/test/graphql-docs/graphql-docs_test.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | require 'test_helper'
4 |
5 | class GraphQLDocsTest < Minitest::Test
6 | def test_that_it_requires_a_file_or_string
7 | assert_raises ArgumentError do
8 | GraphQLDocs.build({})
9 | end
10 | end
11 |
12 | def test_it_demands_string_argument
13 | assert_raises TypeError do
14 | GraphQLDocs.build(filename: 43)
15 | end
16 |
17 | assert_raises TypeError do
18 | GraphQLDocs.build(schema: 43)
19 | end
20 | end
21 |
22 | def test_it_needs_a_file_that_exists
23 | assert_raises ArgumentError do
24 | GraphQLDocs.build(filename: 'not/a/real/file')
25 | end
26 | end
27 |
28 | def test_it_needs_one_or_the_other
29 | assert_raises ArgumentError do
30 | GraphQLDocs.build(filename: 'http://graphql.org/swapi-graphql/', schema: File.join(fixtures_dir, 'gh-api.json'))
31 | end
32 |
33 | assert_raises ArgumentError do
34 | GraphQLDocs.build
35 | end
36 | end
37 |
38 | def test_it_accepts_class_schema
39 | GraphQLDocs.build(schema: MySchema)
40 | end
41 | end
42 |
--------------------------------------------------------------------------------
/test/graphql-docs/parser_test.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | require 'test_helper'
4 |
5 | class ParserTest < Minitest::Test
6 | def setup
7 | @ghapi = File.read(File.join(fixtures_dir, 'gh-schema.graphql'))
8 | @swapi = File.read(File.join(fixtures_dir, 'sw-schema.graphql'))
9 | @gh_parser = GraphQLDocs::Parser.new(@ghapi, {})
10 | @gh_results = @gh_parser.parse
11 | end
12 |
13 | def test_it_accepts_schema_class
14 | schema = MySchema
15 |
16 | results = GraphQLDocs::Parser.new(schema, {}).parse
17 | assert_equal 'myField', results[:operation_types][0][:fields][0][:name]
18 | assert_equal "Title paragraph.\n ```\n line1\n line2\n line3\n ```", results[:operation_types][0][:fields][0][:description]
19 | end
20 |
21 | def test_types_are_sorted
22 | names = @gh_results[:object_types].map { |t| t[:name] }
23 | assert_equal names.sort, names
24 | end
25 |
26 | def test_connections_are_plucked
27 | issue = @gh_results[:object_types].find { |t| t[:name] == 'Issue' }
28 | refute issue[:connections].empty?
29 | end
30 |
31 | def test_knows_implementers_for_interfaces
32 | comment = @gh_results[:interface_types].find { |t| t[:name] == 'Comment' }
33 | refute comment[:implemented_by].empty?
34 | end
35 |
36 | def test_groups_items_by_type
37 | assert @gh_results[:input_object_types]
38 | assert @gh_results[:object_types]
39 | assert @gh_results[:scalar_types]
40 | assert @gh_results[:interface_types]
41 | assert @gh_results[:enum_types]
42 | assert @gh_results[:union_types]
43 | assert @gh_results[:mutation_types]
44 | assert @gh_results[:directive_types]
45 | end
46 |
47 | def test_directives
48 | names = @gh_results[:directive_types].map { |t| t[:name] }
49 | assert_equal %w[deprecated include oneOf preview skip specifiedBy], names
50 |
51 | preview_directive = @gh_results[:directive_types].find { |t| t[:name] == 'deprecated' }
52 | assert_equal %i[FIELD_DEFINITION ENUM_VALUE ARGUMENT_DEFINITION INPUT_FIELD_DEFINITION], preview_directive[:locations]
53 |
54 | assert_equal 'Marks an element of a GraphQL schema as no longer supported.', preview_directive[:description]
55 | reason_arg = preview_directive[:arguments].first
56 | assert_equal 'reason', reason_arg[:name]
57 | assert_equal 'Explains why this element was deprecated, usually also including a suggestion for how to access supported similar data. Formatted in [Markdown](https://daringfireball.net/projects/markdown/).', reason_arg[:description]
58 | end
59 |
60 | def test_mutationless_schemas_do_not_explode
61 | parser = GraphQLDocs::Parser.new(@swapi, {})
62 | results = parser.parse
63 |
64 | assert_empty results[:mutation_types]
65 | end
66 |
67 | def test_scalar_inputs_for_mutations_are_supported
68 | schema = <<-SCHEMA
69 | type Query {
70 | foo : ID
71 | }
72 | input MessageInput {
73 | content: String
74 | author: String
75 | }
76 | type Mutation {
77 | bar(id: ID!, input: MessageInput) : ID
78 | }
79 | SCHEMA
80 |
81 | parser = GraphQLDocs::Parser.new(schema, {})
82 | results = parser.parse
83 |
84 | assert results[:mutation_types]
85 | end
86 |
87 | def test_schemas_with_quote_style_comments_works
88 | schema = <<-SCHEMA
89 | type Query {
90 | profile: User
91 | }
92 |
93 | """
94 | A user
95 | """
96 | type User {
97 | """
98 | The id of the user
99 | """
100 | id: String!
101 |
102 | """
103 | The email of user
104 | """
105 | email: String
106 | }
107 | SCHEMA
108 |
109 | parser = GraphQLDocs::Parser.new(schema, {})
110 |
111 | results = parser.parse
112 | assert results[:object_types]
113 | user = results[:object_types].first
114 | assert_equal 'The id of the user', user[:fields].first[:description]
115 | end
116 |
117 | def test_deprecations
118 | schema = MySchema
119 |
120 | fields = GraphQLDocs::Parser.new(schema, {}).parse[:operation_types][0][:fields]
121 |
122 | refute fields[0][:is_deprecated]
123 | assert fields[1][:is_deprecated]
124 | assert fields[2][:arguments][0][:is_deprecated]
125 | end
126 | end
127 |
--------------------------------------------------------------------------------
/test/graphql-docs/renderer_test.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | require 'test_helper'
4 |
5 | class RendererTest < Minitest::Test
6 | def setup
7 | @swapi = File.read(File.join(fixtures_dir, 'sw-schema.graphql'))
8 | @parsed_schema = GraphQLDocs::Parser.new(@swapi, {}).parse
9 | @renderer = GraphQLDocs::Renderer.new(@parsed_schema, GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS)
10 | end
11 |
12 | def test_that_rendering_works
13 | contents = @renderer.render('R2D2', type: 'Droid', name: 'R2D2')
14 |
15 | assert_match %r{The direction in which to order projects by the specified field.
\s+R2D2
', contents 22 | end 23 | 24 | def test_that_unsafe_html_is_not_blocked_by_default 25 | contents = @renderer.to_html('Oh hello') 26 | 27 | assert_equal 'Oh hello
', contents 28 | end 29 | 30 | def test_that_unsafe_html_is_blocked_when_asked 31 | renderer = GraphQLDocs::Renderer.new(@parsed_schema, GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge({ 32 | pipeline_config: { 33 | pipeline: 34 | %i[ExtendedMarkdownFilter 35 | EmojiFilter 36 | TableOfContentsFilter], 37 | context: { 38 | gfm: false, 39 | unsafe: false, 40 | asset_root: 'https://a248.e.akamai.net/assets.github.com/images/icons' 41 | } 42 | } 43 | })) 44 | contents = renderer.to_html('Oh **hello**') 45 | 46 | assert_equal 'Oh hello
', contents 47 | end 48 | 49 | def test_that_filename_accessible_to_filters 50 | renderer = GraphQLDocs::Renderer.new(@parsed_schema, GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge({ 51 | pipeline_config: { 52 | pipeline: 53 | %i[ExtendedMarkdownFilter 54 | EmojiFilter 55 | TableOfContentsFilter 56 | AddFilenameFilter], 57 | context: { 58 | gfm: false, 59 | unsafe: true, 60 | asset_root: 'https://a248.e.akamai.net/assets.github.com/images/icons' 61 | } 62 | } 63 | })) 64 | contents = renderer.render('', type: 'Droid', name: 'R2D2', filename: '/this/is/the/filename') 65 | assert_match %r{/this/is/the/filename}, contents 66 | end 67 | end 68 | 69 | class AddFilenameFilter < HTML::Pipeline::Filter 70 | def call 71 | doc.search('span[@id="fill-me"]').each do |span| 72 | span.inner_html = context[:filename] 73 | end 74 | doc 75 | end 76 | 77 | def validate 78 | needs :filename 79 | end 80 | end 81 | -------------------------------------------------------------------------------- /test/test_helper.rb: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | $LOAD_PATH.unshift File.expand_path('../lib', __dir__) 4 | require 'graphql-docs' 5 | 6 | require 'minitest/autorun' 7 | require 'minitest/pride' 8 | require 'minitest/focus' 9 | 10 | def fixtures_dir 11 | File.join(File.dirname(__FILE__), 'graphql-docs', 'fixtures') 12 | end 13 | 14 | def output_dir 15 | File.join(fixtures_dir, 'output') 16 | end 17 | def clean_up_output 18 | FileUtils.rm_rf(output_dir) 19 | end 20 | clean_up_output 21 | 22 | class QueryType < GraphQL::Schema::Object 23 | field :my_field, Int, "Title paragraph. 24 | ``` 25 | line1 26 | line2 27 | line3 28 | ```", null: false 29 | 30 | field :deprecated_field, Int, deprecation_reason: "Not useful any more" 31 | 32 | field :field_with_deprecated_arg, Int do 33 | argument :my_arg, Int, required: false, deprecation_reason: "Not useful any more" 34 | end 35 | end 36 | 37 | class MySchema < GraphQL::Schema 38 | query QueryType 39 | end 40 | --------------------------------------------------------------------------------