-
Notifications
You must be signed in to change notification settings - Fork 120
/
config-example.yml
455 lines (391 loc) · 17.3 KB
/
config-example.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
# This config will not run "as-is" and will need to be modified. You can see a minimal working
# config in /examples/config.yml
#
# Environment variable substitution will be performed by SpectaQL on all strings encountered
spectaql:
# Optional Boolean indicating whether to omit the HTML <body/> and generate the documentation content only
# Default: false
embeddable: false
# Optional Boolean indicating whether to embed all resources (CSS and JS) into the same file
# Default: false
oneFile: false
# Optional path to the target build directory.
# Set to null to not write the output to the filesystem, making it only available via the API (default: public)
#
# Default: public
targetDir: path/to/output
# Optional path to an image to use as the logo in the top-left of the output
logoFile: path/to/logo.png
# Optional boolean indicating whether to encode the local logoFile and embed the image as Base64
# into the resulting HTML. Only applicable if providing the logoFile.
#
# Default: false
embedLogo: false
# Optional boolean indicating whether to preserve the filename of the logo provided.
# If false, the logo name will default to "logo"
preserveLogoName: false
# Optional URL to an image to use in your logo. This string will be provided as-is
# to the HTML output. Should not be used with logoFile and its related options as
# this will take precedence over the logoFile.
logoUrl: https://yoursite.com/images/logo.png
# Control the height of your logo here. Can be useful if your logo is SVG or an
# inappropriate size.
#
# Default: None; No "height" property will be set on the logo
logoHeightPx: 18
# Optional path to an image to use as a favicon for the site when it's not embedded
faviconFile: path/to/favicon.png
# Optional boolean indicating whether to encode the local favicon and embed the image as Base64
# into the resulting HTML. Only applicable if providing the faviconFile.
#
# Default: false
embedFavicon: false
# Optional boolean indicating whether to preserve the filename of the faviconFile provided.
# If false, the favicon name will default to "favicon"
preserveFaviconName: false
# Optional URL to an image to use in your favicon. This string will be provided as-is
# to the HTML output. Should not be used with faviconFile and its related options as
# this will take precedence over the faviconFile.
faviconUrl: https://yoursite.com/images/favicon.png
# Optional string specifying a path to a theme directory to use for your build.
#
# Themes rely on a directory structure convention that overlays your customizations and enhancements
# on top of the default theme provided by SpectaQL. See /examples/themes for more.
#
# Also, a few built-in themes can be used by specifying them by name:
# "default": Our default theme
# "basic": Outputs the same HTML structure as the "default" theme, but with minimal CSS styling
# "spectaql": Outputs the same HTML structure as the "default" theme, but with some CSS enhancements
#
# Default: "default"
themeDir: path/to/theme
# If you're embedding SpectaQL's output, and you've got something like a Nav Bar that
# gets in the way, you can use this value to adjust the scroll offset
#
# Default: None; No "scroll-padding-top" style will be applied.
scrollPaddingTopPx: 0
# If an interpolated reference is not found, should SpectaQL throw an error? Otherwise, a warning
# will be logged.
#
# Default: true
errorOnInterpolationReferenceNotFound: true
# Would you like to display all the servers listed in the servers area of your config? Otherwise,
# it will try to display just the one marked "production: true".
#
# Default: false
displayAllServers: false
# Would you like the "run" function to resolve with an object containing the output as a string?
# Useful if you are using SpectaQL as a dependency (as opposed to running the binary executable)
#
# Default: true
resolveWithOutput: true
introspection:
##############################################
# These options specify where/how to get the information required to generate your
# documentation.
#
# Each of these have corresponding CLI options where they can be expressed instead of here.
# The CLI options will take precedence over what is in your config file
#
# 1 and only 1 of the following options must be provided:
#
# File containing a GraphQL Schema Definition written in SDL.
# Can also pass an array of paths (or glob supported by @graphql-tools/load-files)
# like so:
# schemaFile:
# - path/to/schema/part1.gql
# - path/to/schema/part2.gql
schemaFile: path/to/schema.gql
# File containing Introspection Query response in JS module export, or JSON format
introspectionFile: path/to/introspection.js[on]
# URL of the GraphQL endpoint to hit if you want to generate the documentation based on live Introspection Query results
# NOTE: If not using introspection.url OR servers[], you need to provide x-url below
url: https://yoursite.com/graphql
#
#
##############################################
# If using the "url" option above, any headers (such as Authorization) can be added here. This
# can also be added via the CLI options
headers:
Authorization: Bearer s3cretT0k2n
# Some helpful options for those who are an "SDL-first" shop and/or want to get your metadata into
# SpectaQL during the SDL ingestion.
spectaqlDirective:
# Boolean indicating whether to enable and process the @spectaql directive
#
# Default: true
enable: true
# String indicating the name to use for the SpectaQL directive, e.g. "@spectaql"
# This should be inconsequential in the end since it should be removed
# from your resulting Schema by SpectaQL
#
# Default: 'spectaql'
directiveName: 'spectaql'
# String indicating the name to use for the Type used in the "options" array that can be passed
# to the SpectaQL directive.
# This should be inconsequential in the end since it should be removed
# from your resulting Schema by SpectaQL
#
# Default: 'SpectaQLOption'
optionsTypeName: 'SpectaQLOption'
#
#
##############################################
##############################################
# These options are for random display or augmentation related things that didn't
# really fit anywhere else.
#
# Whether you would like to strip any trailing commas from the descriptions to keep
# things fresh and clean.
#
# Default: false
removeTrailingPeriodFromDescriptions: false
# What manipulation of the query/mutation/subscription name would you like to perform to determine
# the name in query examples? Possible values:
#
# - none: will use same exact name as query)
# - capitalizeFirst: will capitalize the first letter and leave the rest.
# - capitalize: will capitalize the first letter and convert the rest to lower case.
# - camelCase
# - snakeCase
# - upperCase: all letters to upper case.
# - lowerCase: all letters to lower case.
queryNameStrategy: none
# When generating a Query or Mutation example, to what maximum depth should any nested fields
# be represented before a fragment placeholder is rendered?
#
# Default: 1
fieldExpansionDepth: 1
# Include support for @deprecated field on InputType fields.
# NOTE: Be careful, it appears that if you mark an InputType field as deprecated but do NOT set
# this option to `true`, the field will be removed from the schema completely.
#
# Default: false
inputValueDeprecation: false
#
#
##############################################
##############################################
# These options specify how, where and if any "metadata" information is to be added to your Introspection
# Query results IF it is not already present. If you are not dealing with metadata, or you have already
# baked it into your Introspection Query results somehow (on the server-side, for example) then you
# can ignore these options completely.
#
# File that contains your metadata data in JS module export, or JSON format
metadataFile: path/to/metadata.js[on]
# The path to a key from which to read the documentation-related metadata at each level of your metadata file.
# Defaults to 'documentation', but in case you use a different name, or have a complex/nested metadata structure, you can
# specify it here.
#
# Default: documentation
metadatasReadPath: documentation
# The metadata that was just read from the above key path will be woven into your Introspection Query results.
# This option specifies the key path where that data will be written at each level.
#
# ***
# In order to ensure that the metadata you've written can be found later on down the line, this value
# should be set the same as the "metadatasPath" option below
# ***
#
# Defaults to 'documentation', but in case you have a complex/nested metadata structure, you can
# specify it here.
#
# Default: documentation
metadatasWritePath: documentation
#
#
##############################################
##############################################
# These options specify how, where and if any "metadata" information is to be found, or
# used/ignored when processing your documentation.
#
# The key path in your Introspection Query results where metadata supported by this library can
# be found.
# Defaults to 'documentation', but in case you have a complex/nested metadata structure, you can
# specify it here.
#
# Default: documentation
metadatasPath: documentation
# Whether or not to look for and use metadata in your data. If turned off, metadata will be ignored
# even if it's there
#
# Default: true
metadatas: true
#
#
##############################################
# This allows you to specify a custom path to a JS module to handle the generation of
# example values for your schema.
# Default: none
dynamicExamplesProcessingModule: path/to/examples.js
##############################################
# These options specify what the default behavior should be
# (regarding documented vs non-documented) in the absence of
# metadata directives on a given item
# Whether to document any Queries at all, in the absence of a metadata directive
# Default: true
queriesDocumentedDefault: true
# Whether to document an individual Query, in the absence of a metadata directive
# Default: true
queryDocumentedDefault: true
# Whether to document a Query Argument, in the absence of a metadata directive
# Default: true
queryArgDocumentedDefault: true
# Hide any Queries with undocumented return types so as not to reference something
# that seemingly does not exist.
# Default: true
hideQueriesWithUndocumentedReturnType: true
# Whether to document any Mutations at all, in the absence of a metadata directive
# Default: true
mutationsDocumentedDefault: true
# Whether to document an individual Mutation, in the absence of a metadata directive
# Default: true
mutationDocumentedDefault: true
# Whether to document a Mutation Argument, in the absence of a metadata directive
# Default: true
mutationArgDocumentedDefault: true
# Hide any Mutations with undocumented return types so as not to reference something
# that seemingly does not exist.
# Default: true
hideMutationsWithUndocumentedReturnType: true
# Whether to document any Subscriptions at all
# Default: true
subscriptionsDocumentedDefault: true
# Whether to document an individual Subscription, in the absence of a metadata directive
# Default: true
subscriptionDocumentedDefault: true
# Whether to document a Subscription Argument, in the absence of a metadata directive
# Default: true
subscriptionArgDocumentedDefault: true
# Hide any Subscriptions with undocumented return types so as not to reference something
# that seemingly does not exist.
# Default: true
hideSubscriptionsWithUndocumentedReturnType: true
# Hide any Types that are not used anywhere in your schema after other things have been hidden.
# Default: true
hideUnusedTypes: true
# Whether to document any Types at all
# Default: true
objectsDocumentedDefault: true
# Whether to document an individual Type, in the absence of a metadata directive
# Default: true
objectDocumentedDefault: true
# Whether to document any Input Object types at all
# Default: true
inputsDocumentedDefault: true
# Whether to document an individual Input Object, in the absence of a metadata directive
# Default: true
inputDocumentedDefault: true
# Whether to document any Enums at all
# Default: true
enumsDocumentedDefault: true
# Whether to document an individual Enum, in the absence of a metadata directive
# Default: true
enumDocumentedDefault: true
# Whether to document any Unions at all
# Default: true
unionsDocumentedDefault: true
# Whether to document an individual Union, in the absence of a metadata directive
# Default: true
unionDocumentedDefault: true
# Hide Union possibleTypes that are not documented so as not to reference something
# that seemingly does not exist.
# Default: true
hideUnionTypesOfUndocumentedType: true
# Whether to document an individual Field, in the absence of a metadata directive
# Default: true
fieldDocumentedDefault: true
# Hide any fields of undocumented types so as not to reference something
# that seemingly does not exist.
# Default: true
hideFieldsOfUndocumentedType: true
# Whether to document an individual Input Field, in the absence of a metadata directive
# Default: true
inputFieldDocumentedDefault: true
# Hide any inputFields of undocumented types so as not to reference something
# that seemingly does not exist.
# Default: true
hideInputFieldsOfUndocumentedType: true
# Whether to document an individual Argument, in the absence of a metadata directive
# Default: true
argDocumentedDefault: true
# Hide any args of undocumented types so as not to reference something
# that seemingly does not exist.
# Default: true
hideArgsOfUndocumentedType: true
#
#
##############################################
extensions:
# Utilize the 'graphql-scalars' library when generating examples for scalars it supports that
# do not have an example already set via some other method. Usually this is a good
# thing to have on, but it is possible to turn it off.
# Default: true
graphqlScalarExamples: true
servers:
# NOTE: If not using introspection.url OR servers[], you need to provide x-url
# same format as for OpenAPI Specification https://swagger.io/specification/#server-object
- url: https://yoursite.com/graphql
description: Production Server
# Indicates to use this server's URL as the typical GraphQL request base in the documentation
# If no server entries have this indicator, the first server's URL will be used.
# If no server entries are defined at all, the Introspection URL will be used.
production: true
# A place to list any Headers for your GraphQL API calls
headers:
- name: Authorization
example: Bearer <YOUR_TOKEN_HERE>
comment: Your API token from the dashboard. Must be included in all API calls.
info:
# Tries to adhere to OpenAPI Specification https://swagger.io/specification/#info-object
# Will be used to populate the Welcome section of the output
##############################################
# Introduction area flags
#
# Set to true to do no Introduction area rendering at all. Supersedes the below options
# Default: false
x-hideIntroduction: false
# Set to true to not render a friendly Welcome section based on the description in this area
# Default: false
x-hideWelcome: false
# Set to true to not render your intro items
# Default: false
x-hideIntroItems: false
# Set to true to not render the deprecated label
# Default: false
x-hideIsDeprecated: false
# Set to true to not render the deprecation reason
# Default: false
x-hideDeprecationReason: false
#
##############################################
description: Your description here
version: 1.0.0
title: Your Welcome title here
# This is non-standard and optional. If omitted, will use "title". Also, only relevant
# when building non-embedded.
x-htmlTitle: Your HTML page title here
termsOfService: 'https://yoursite.com/terms'
contact:
name: YourSite Support
email: [email protected]
url: https://yoursite.com/support
license:
name: Apache 2.0
url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
# A non-standard array of items to display in your Introduction Area
x-introItems:
# Can be a Title (for the Nav panel) + URL to simply add a link to somewhere
- title: A silly link to our website!
url: http://yoursite.com
# Can be a Title (for the Nav panel) + description (for the Content panel)
- title: Important thing 1
description: Some important stuff we wanted you to know. Supports `markdown`
# Can be a Title (for the Nav panel) + file that gets loaded (for the Content panel)
- title: Content from file that supports markdown
file: ./examples/data/intro-items-markdown.md
# If you really want to hide the "Documentation by" at the bottom of your output, you can do so here
# Default: false
x-hidePoweredBy: false
# If not using introspection.url OR servers[], you need to provide x-url
x-url: https://yoursite.com/graphql