ReferenceCLIapigenieformat
format
Formats JSON and YAML files containing OpenAPI, Swagger 2.0 or AsyncAPI
schemas, Protobuf (.proto) files and GraphQL (.graphql, .graphqls,
.gql) files.
Usage
apigenie format [OPTIONS] FILESDescription
This command formats JSON and YAML files containing OpenAPI, Swagger 2.0 or
AsyncAPI 3.x schemas. The formatter recognizes the specification by the
openapi, swagger or asyncapi string property of the document root (see
Swagger configuration). Files that contain none of
them are reported as errors and left untouched. Files with the .proto extension are
formatted as proto3 files (see Protobuf configuration),
and files with the .graphql, .graphqls or .gql extension as GraphQL
documents (see GraphQL configuration).
This formatting helps to:
- maintain a consistent style for your OpenAPI schemas
- enhance readability of the schemas
- facilitate collaboration on schemas among multiple developers
API Genie formatter works with all supported file formats. However, it is important to note that it’s not a generic JSON/YAML parser.
The formatter can process partially invalid schemas. It fails only when it
encounters JSON or YAML syntax error. This is different from commands
like lint or diff, which need valid OpenAPI schemas.
Currently, the formatter can change the following aspects of input schemas:
- Indentation size, line endings, the final line break and the width at which long YAML values are folded
- The YAML styles of strings, keys, sequences and mappings, globally or for chosen fields
- Order of properties for objects defined by the OpenAPI specification, at every depth of OpenAPI 3.0, 3.1 and 3.2 documents, and of the names in maps such as components, properties or media types
It never changes what a document means: formatting the output again gives the same output, and it holds the same values as the input.
Comments
The formatter keeps comments: the YAML comments of OpenAPI, Swagger and
AsyncAPI documents (at the top and the end of the file, above keys, at the end
of lines, inside sequences, between entries and after the last entry), the
comments of Protobuf files and the # comments of GraphQL documents. A comment
directly above a key belongs to that key and moves with it when properties are
sorted; a comment at the top of the file that a blank line separates from the
first key stays at the top. JSON has no comments, so a YAML document written as
JSON loses them. --strip-comments drops the comments.
With the best-fit string and key styles, strings that YAML 1.1 parsers (such
as PyYAML, SnakeYAML or go-yaml v2) would read as booleans, numbers or merge
keys are written in double quotes: yes, No, on, OFF, y, n, 0755,
0b101, 1_000, 1:30, << and the like. The original style keeps the
quoting of the source.
Specifying property order
Formatter command can be configured to list properties of OpenAPI objects in specific order. This greatly helps to improve the readability of OpenAPI schemas.
Below are supported modes of ordering properties of schema objects:
- original - list properties in the same order as in input file. This is the default behaviour.
- sorted - sort properties alphabetically
- custom - users can define property order in the configuration file
Each mode can be useful in specific situations. For example, original mode
is useful when modifying existing schemas to avoid excessive changes.
Sorted mode is a natural order for elements like path items or shared
schemas. Finally, custom order allows users to define a specific order for
properties within schema objects, which can be beneficial for request/response
bodies and operations where placing summary and description properties at
the beginning improves readability.
Property mode can be configured
- Globally (default) for all schema objects
- Per schema object type
Example - Preserve original property order for all schema objects
commands:
format:
openapi:
property_order:
default: originalExample - Sort all path items within Paths objects alphabetically
commands:
format:
openapi:
property_order:
paths: sortedExample - Specify custom property order for Operation objects
commands:
format:
openapi:
property_order:
operation:
# place summary and description at the beginning, to help
# understand operation's purpose
- summary
- description
- tags
- operationId
- externalDocs
- deprecated
- parameters
- requestBody
- responses
- callbacks
- security
- serversProperties not explicitly listed in the configuration for a specific schema object type will be placed after the listed ones, in the same order as in the input file.
Example
If the configuration for the Contact object looks like:
commands:
format:
openapi:
property_order:
contact:
- name
- url
- emailand the actual contact data before formatting looks like:
openapi: 3.1.0
info:
contact:
x-team: awesome
name: You
email: you@example.com
url: your.site
x-audience: internal
x-stability: stable
...formatting it will change it to:
openapi: 3.1.0
info:
contact:
name: You
url: your.site
email: you@example.com
x-team: awesome
x-audience: internal
x-stability: stable
...Options
Without options, formatter formats input file(-s) using default configuration. The resulting content is written back into input files, without changing their format.
apigenie format input1.yaml input2.json–config FILE
Optional path to the configuration file. If not specified, the default configuration is used. For details, see the configuration section.
apigenie format --config api-style-guide.yaml input1.yaml input2.json–check
Checks that the files are formatted, without writing anything. The path of
every file that formatting would change is printed on its own line, and the
command exits with 1 when there is at least one. A file whose output format
differs from its own (see Swagger configuration)
always counts as a change. Files with syntax errors and unsupported documents
are reported as without --check. Cannot be combined with --output.
apigenie format --check api/*.yaml–strip-comments
Drops the comments of the files instead of keeping them: YAML comments of
OpenAPI, Swagger and AsyncAPI documents, // and /* */ comments of Protobuf
files and # comments of GraphQL documents. GraphQL descriptions are part of
the schema and are kept. A # prettier-ignore comment is dropped too, so the
definition after it is formatted.
apigenie format --strip-comments api/openapi.yaml–openapi-fragment KIND
Formats the files as fragments of OpenAPI documents, such as a schema kept in
its own file and referenced with $ref. KIND is the object at the root of the
files: schema, pathItem, operation, parameter, requestBody,
response, header, example, link, securityScheme or components. The
objects inside the fragment are recognized as in a whole document. Protobuf and
GraphQL files are formatted as usual.
apigenie format --openapi-fragment schema schemas/*.yaml–output OUTPUT
Optional path to the output file. If not specified, resulting content is written to the input file.
If this option is given, formatter processes only a single file at a time.
Note that the output format is determined by this file’s extension. So this
can be used to convert between JSON and YAML representations. A .proto or
GraphQL input is written in its own format, whatever the output extension.
apigenie format input.yaml --output output.jsonExit status
The command exits with 0 when every file was formatted or, with --check, is
already formatted, and with 1 when, with --check, a file is not formatted. It
exits with 2 when a file has syntax errors or is not a supported document (the
other files are still formatted or checked), or when the options can’t be used
together. See the exit statuses shared by the three binaries.
Configuration
Formatter stores its configuration for OpenAPI documents under the
#/commands/format/openapi key, and for AsyncAPI documents under the
#/commands/format/asyncapi key in the configuration file (see
AsyncAPI configuration). Swagger 2.0 documents use
the #/commands/format/swagger key (see
Swagger configuration). Protobuf files use the
#/commands/format/protobuf key (see
Protobuf configuration), and GraphQL files the
#/commands/format/graphql key (see
GraphQL configuration). All sections are optional. See the global configuration
section to understand how this file is structured.
A configuration replaces the defaults as a whole: the presets named by
extends are applied first, in order, then the keys of the openapi section.
Unknown keys, unknown object names and invalid values are errors, reported with
their line and column in the configuration file; nothing is formatted then.
Example - Recommended settings, with CRLF line endings and descriptions written as literal blocks
commands:
format:
extends:
- recommended
openapi:
newline: crlf
style_overrides:
- fields: [description]
string: literalformat
The output format: yaml, json or original. Without it, or with
original, every file keeps its own format. With another format, formatting
api.json in place writes api.yaml next to it.
indent
The number of spaces of one level of indentation, from 2 to 9. The default is 2.
force_array_indent
Indents the elements of YAML block sequences under their key (true), instead
of writing them at the level of the key (false, the default).
style
The styles of YAML values: string (original, best-fit, plain,
single-quoted, double-quoted, literal, folded), array and object
(original, best-fit, block, flow) and key (original, best-fit,
plain, single-quoted, double-quoted). The default is original for all
of them, which keeps the styles of the input.
Layout
| Key | Values | Default | Effect |
|---|---|---|---|
line_width |
0 to 100000 | 0 | Folds long YAML scalars at this width. 0 never folds them. |
newline |
lf, crlf |
lf |
The line endings of the output, YAML and JSON. |
final_newline |
true, false |
the writer’s | Whether the output ends with a line break. Without it, YAML and indented JSON end with one. |
document_marker |
true, false |
false |
Starts YAML documents with ---. |
style_overrides
A list of rules giving the values of some fields their own YAML styles. A rule
selects values by fields (the names of their fields), by objects (the
kinds of the objects holding them), or by both, and sets one
or more of string, array and object, with the values of
style. A rule without objects applies to the fields of OpenAPI
objects only, never to those inside example values or extensions. When several
rules match a value, the later ones win.
Example - Literal descriptions, and flow sequences for the tags of operations and the required properties of schemas
commands:
format:
openapi:
style_overrides:
- fields: [description]
string: literal
- fields: [tags]
objects: [operation]
array: flow
- fields: [required]
objects: [schema]
array: flowproperty_order
Keys of the property_order section are default, which sets the order of
every object without an order of its own (sorted or original, the default),
or one of the names below. Each key accepts sorted, original or an array of
property names in the desired order. Properties that an array does not list are
placed after the listed ones, in their order in the input file; this also holds
for fields of later OpenAPI versions and for extensions. The last column shows
the order used by the recommended configuration.
| Key | Object | Recommended order |
|---|---|---|
openapi |
OpenAPI (document root) | openapi, $self, info, jsonSchemaDialect, servers, paths, webhooks, components, security, tags, externalDocs |
info |
Info | title, summary, description, version, termsOfService, contact, license |
contact |
Contact | name, url, email |
license |
License | name, identifier, url |
server |
Server | url, name, description, variables |
serverVariable |
Server Variable | description, default, enum |
paths |
Paths (the path templates) | sorted |
pathItem |
Path Item (in paths, webhooks, callbacks and components) | $ref, summary, description, parameters, get, post, put, patch, delete, query, options, head, trace, additionalOperations, servers |
operation |
Operation (also query and additionalOperations) |
tags, summary, operationId, description, externalDocs, deprecated, parameters, requestBody, responses, callbacks, security, servers |
components |
Components | schemas, responses, parameters, requestBodies, headers, mediaTypes, pathItems, securitySchemes, links, callbacks, examples |
externalDocumentation |
External Documentation (also of schemas) | description, url |
parameter |
Parameter | name, in, description, required, deprecated, style, allowEmptyValue, explode, allowReserved, schema, content, example, examples |
requestBody |
Request Body | description, required, content |
mediaType |
Media Type | description, schema, itemSchema, encoding, prefixEncoding, itemEncoding, example, examples |
encoding |
Encoding | contentType, style, headers, explode, allowReserved, encoding, prefixEncoding, itemEncoding |
responses |
Responses (the status codes of an operation) | sorted |
response |
Response | summary, description, headers, content, links |
example |
Example | summary, description, dataValue, serializedValue, value, externalValue |
link |
Link | description, server, operationRef, operationId, parameters, requestBody |
header |
Header | name, description, required, deprecated, allowEmptyValue, style, explode, allowReserved, schema, content, example, examples |
tag |
Tag | name, summary, description, parent, kind, externalDocs |
reference |
Reference (see below) | $ref, summary, description |
schema |
Schema, at any depth | $schema, $id, $anchor, $dynamicAnchor, $ref, $dynamicRef, title, description, $comment, type, format, nullable, const, enum, numeric, string, array and object keywords, allOf, oneOf, anyOf, not, if, then, else, default, examples, example, readOnly, writeOnly, deprecated, discriminator, xml, externalDocs, $defs, definitions |
discriminator |
Discriminator | propertyName, mapping, defaultMapping |
xml |
XML | nodeType, name, namespace, prefix, attribute, wrapped |
securityScheme |
Security Scheme | name, description, type, in, scheme, bearerFormat, flows, openIdConnectUrl, oauth2MetadataUrl, deprecated |
oauthFlows |
OAuth Flows | implicit, password, clientCredentials, authorizationCode, deviceAuthorization |
oauthFlow |
OAuth Flow | authorizationUrl, deviceAuthorizationUrl, tokenUrl, refreshUrl, scopes |
componentNames |
The names in each map of Components | default |
webhooks |
The names of webhooks | default |
callbacks |
The names in the callbacks map of an operation |
default |
callback |
Callback (its runtime expressions) | default |
content |
The media types of a content map |
default |
headers |
The names of a headers map |
default |
properties |
The names in properties, patternProperties, $defs and dependentSchemas |
default |
scopes |
OAuth scopes | default |
extension |
Everything inside the value of an x- field |
default |
exampleValue |
Everything inside example payloads, default, const and enum values |
default |
The keys of named maps and raw values are independent of the object keys: for
example, componentNames: sorted with properties: original and a fixed
schema order sorts the schemas of the components by name, keeps the
properties of each schema in their order and puts the keywords of each schema
in the fixed order. Arrays are never sorted.
Example - Sorted component names, everything else as in the input
commands:
format:
openapi:
property_order:
componentNames: sortedOpenAPI versions and object recognition
The formatter recognizes the objects of OpenAPI 3.0, 3.1 and 3.2 by their place in the document, from the root down, so names chosen by the author (paths, component names, schema properties) are never mistaken for fields:
- Schemas are recognized at every depth: under
properties,patternProperties,additionalProperties,items(a schema, or the array of schemas of 3.0),prefixItems,allOf,anyOf,oneOf,not,if,then,else,$defs,dependentSchemas,contains,propertyNames,unevaluatedItems,unevaluatedPropertiesandcontentSchema, and under theitemSchemaof a 3.2 media type. Boolean schemas are left as they are. - Path items and operations are recognized in
paths,webhooks, thecallbacksof operations at any depth and in components, and so are 3.2queryoperations andadditionalOperations. - Headers, media types, encodings (also 3.2
prefixEncodinganditemEncoding) and examples are recognized wherever the specification allows them, including the content and examples of headers. - Example payloads,
default,constandenumvalues and the values ofx-fields are data: they are never formatted as OpenAPI objects, and their keys follow theexampleValueandextensionorders.
An object in a place that allows a Reference Object (a parameter, request body,
media type, response, header, example, link, callback, security scheme or path
item) follows the reference order when it has a $ref field. A path item is
a Reference Object only when it has no other fields than $ref, summary and
description: next to its operations, $ref is merged with them. A schema with
$ref is always a schema, because $ref is a schema keyword since 3.1; the
schema order of the recommended configuration puts $ref first.
A document that is valid YAML or JSON is formatted even when it is not a valid OpenAPI document; values in unexpected places keep the default order. YAML anchors and aliases are not kept: each alias is written as a copy of its anchor’s value, in YAML as in JSON.
AsyncAPI configuration
AsyncAPI documents are formatted with settings stored under the
#/commands/format/asyncapi key. The section accepts the same keys as the
OpenAPI one: format, indent, force_array_indent, style and
property_order.
Example - Recommended settings for both specifications, with a custom
property order for AsyncAPI Operation objects
commands:
format:
extends:
- recommended
asyncapi:
indent: 2
property_order:
channels: sorted
operation:
- action
- channel
- summary
- description
- messages
- replyKeys of the property_order section are default or one of the following
names of AsyncAPI 3 objects.
Each key accepts sorted, original or an array of property names in the
desired order. The last column shows the order used by the recommended
configuration.
| Key | Object | Recommended order |
|---|---|---|
asyncapi |
AsyncAPI (document root) | asyncapi, id, info, servers, defaultContentType, channels, operations, components |
info |
Info | title, version, description, termsOfService, contact, license, tags, externalDocs |
contact |
Contact | name, url, email |
license |
License | name, url |
servers |
Servers | original |
server |
Server | host, protocol, protocolVersion, pathname, title, summary, description, variables, security, tags, externalDocs, bindings |
serverVariable |
Server Variable | enum, default, description, examples |
channels |
Channels | sorted |
channel |
Channel | address, title, summary, description, servers, parameters, messages, tags, externalDocs, bindings |
parameter |
Parameter | enum, default, description, examples, location |
operations |
Operations | original |
operation |
Operation | action, channel, title, summary, description, security, tags, externalDocs, bindings, traits, messages, reply |
operationTrait |
Operation Trait | title, summary, description, security, tags, externalDocs, bindings |
operationReply |
Operation Reply | address, channel, messages |
operationReplyAddress |
Operation Reply Address | description, location |
message |
Message | name, title, summary, description, contentType, correlationId, headers, payload, tags, externalDocs, bindings, examples, traits |
messageTrait |
Message Trait | name, title, summary, description, contentType, correlationId, headers, tags, externalDocs, bindings, examples |
messageExample |
Message Example | name, summary, headers, payload |
correlationId |
Correlation ID | description, location |
tag |
Tag | name, description, externalDocs |
externalDocumentation |
External Documentation | description, url |
components |
Components | schemas, servers, channels, operations, messages, securitySchemes, serverVariables, parameters, correlationIds, replies, replyAddresses, externalDocs, tags, operationTraits, messageTraits, serverBindings, channelBindings, operationBindings, messageBindings |
reference |
Reference | $ref |
schema |
Schema (component, message payload/headers) | title, description, type, format, const, enum, default, examples, minimum, exclusiveMinimum, maximum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, items, contains, minItems, maxItems, uniqueItems, required, properties, … |
securityScheme |
Security Scheme | type, description, name, in, scheme, bearerFormat, flows, openIdConnectUrl, scopes |
oauthFlows |
OAuth Flows | implicit, password, clientCredentials, authorizationCode |
oauthFlow |
OAuth Flow | authorizationUrl, tokenUrl, refreshUrl, availableScopes |
bindings |
Server, Channel, Operation, Message Bindings | sorted |
Properties that are not listed in a fixed order are placed after the listed ones, in the same order as in the input file.
Swagger configuration
Swagger 2.0 documents are recognized by the swagger string property of the
document root, and formatted with settings stored under the
#/commands/format/swagger key. The section accepts the same keys as the
OpenAPI one: format, indent, force_array_indent, style and
property_order.
In YAML, the version must be quoted (swagger: "2.0"): an unquoted 2.0 is a
number, and such documents are reported as unsupported. Every file keeps
its own format unless format asks for another one: with format: yaml,
formatting swagger.json in place writes swagger.yaml next to it.
Example - Recommended settings, with sorted definitions and a custom
property order for Operation objects
commands:
format:
extends:
- recommended
swagger:
format: json
indent: 2
property_order:
definitions: sorted
operation:
- operationId
- summary
- tags
- parameters
- responsesKeys of the property_order section are default or one of the following
names of Swagger 2.0 objects. Each key
accepts sorted, original or an array of property names in the desired
order. The last column shows the order used by the recommended
configuration.
| Key | Object | Recommended order |
|---|---|---|
swagger |
Swagger (document root) | swagger, info, host, basePath, schemes, consumes, produces, paths, definitions, parameters, responses, securityDefinitions, security, tags, externalDocs |
info |
Info | title, description, version, termsOfService, contact, license |
contact |
Contact | name, url, email |
license |
License | name, url |
paths |
Paths | sorted |
pathItem |
Path Item | $ref, parameters, get, post, put, patch, delete, options, head |
operation |
Operation | tags, summary, operationId, description, externalDocs, deprecated, schemes, consumes, produces, parameters, responses, security |
externalDocumentation |
External Documentation | description, url |
parameter |
Parameter (in path items, operations and parameters) |
$ref, name, in, description, required, allowEmptyValue, schema, type, format, items, collectionFormat, default, enum, minimum, exclusiveMinimum, maximum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, minItems, maxItems, uniqueItems |
items |
Items (of parameters and headers) | type, format, items, collectionFormat, default, enum, minimum, exclusiveMinimum, maximum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, minItems, maxItems, uniqueItems |
responses |
Responses (of an operation) | sorted |
response |
Response (in operations and responses) |
$ref, description, schema, headers, examples |
header |
Header | description, type, format, items, collectionFormat, default, enum, minimum, …, uniqueItems |
schema |
Schema, including nested ones | $ref, title, description, type, format, enum, default, minimum, exclusiveMinimum, maximum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, items, minItems, maxItems, uniqueItems, required, properties, additionalProperties, … |
xml |
XML | name, namespace, prefix, attribute, wrapped |
definitions |
Definitions (definitions) |
original |
parametersDefinitions |
Parameters Definitions (parameters of the root) |
original |
responsesDefinitions |
Responses Definitions (responses of the root) |
original |
securityDefinitions |
Security Definitions | original |
securityScheme |
Security Scheme | type, description, name, in, flow, authorizationUrl, tokenUrl, scopes |
tag |
Tag | name, description, externalDocs |
Schemas are recognized at any depth: in definitions, in body parameters and
responses, and inside properties, items, additionalProperties and
allOf. Values that are not Swagger objects, such as extensions (x-*),
example, examples, default, enum and scopes, are ordered by the
default setting only.
Properties that are not listed in a fixed order are placed after the listed ones, in the same order as in the input file.
Protobuf configuration
Files with the .proto extension are formatted as proto3 files, with
settings stored under the #/commands/format/protobuf key. The formatter:
- writes every declaration in a canonical layout: one statement per line, normalized spacing, blank lines between top-level declarations and around nested messages, enums and extends
- indents nested declarations by the configured number of spaces
- optionally sorts imports, options and declarations
No comment is lost. Comments are written as // line comments and stay with
their declarations when declarations are sorted. Comments that protoc ignores,
such as those inside a declaration (int32 /* type */ id = 1;), are written
as /* */ comments just before the end of their declaration
(int32 id = 1 /* type */;).
Files that are syntactically correct but break proto3 rules, for example with duplicate field numbers, are formatted. Files with syntax errors are reported with the position of each error and left untouched. Editions and proto2 files are not supported.
| Key | Values | Recommended | Description |
|---|---|---|---|
indent |
1 to 8 | 2 | Number of spaces for one level of nesting. |
sort.imports |
original, sorted |
sorted |
Sorts imports by path. |
sort.options |
original, sorted |
sorted |
Sorts option statements and the options in brackets ([deprecated = true, json_name = "x"]) by name. |
sort.declarations |
original, grouped, sorted |
original |
grouped puts top-level declarations in this order: package, imports, options, services, messages, enums, extends. sorted also sorts services, messages, enums and extends by name within their groups. |
sort.fields |
original, number, name |
original |
Sorts the fields of messages, oneofs and extends. A oneof is placed by its lowest field number (or its name), and its fields are sorted too. |
sort.enum_values |
original, number, name |
original |
Sorts enum values. A first value of zero stays first, as proto3 requires. |
sort.nested_types |
original, sorted |
original |
Sorts the messages, enums and extends nested in a message by name. |
sort.methods |
original, sorted |
original |
Sorts the methods of services by name. |
Without a configuration file, the recommended settings are used. With
extends: [original], nothing is sorted.
Each kind of declaration is sorted among the positions that declarations of
that kind take in its body, so sorting fields, for example, does not move
options, reserved statements or nested messages. Only the grouped and
sorted values of sort.declarations move top-level declarations between
kinds.
Changing the order of fields, enum values or methods does not change the wire format, but it changes the order of declarations in generated code and descriptors. For this reason, the recommended configuration sorts only imports and options.
Example - Recommended settings with 4-space indentation, and fields sorted by number
commands:
format:
extends:
- recommended
protobuf:
indent: 4
sort:
declarations: grouped
fields: number
enum_values: numberapigenie format api/store/v1/*.proto --config api-style-guide.yamlGraphQL configuration
Files with the .graphql, .graphqls or .gql extension are formatted as
GraphQL documents, both schemas (type system definitions) and operations, with
settings stored under the #/commands/format/graphql key. The layout is that
of Prettier: a file formatted by Prettier with the same
line width and indentation is left unchanged. The formatter:
- writes selection sets, fields, enum values and input fields one per line
- keeps argument lists, variable definitions, directives, list and object
values,
implementslists and union members on one line if they fit in the line width, and puts one item per line otherwise - keeps single blank lines between definitions and between members; several blank lines become one, and no blank lines are added
- writes block strings (
""") on lines of their own, and trims the spaces around the text of a single line block string - keeps shorthand queries (
{ ... }) and thequerykeyword as written - optionally sorts definitions and the members of types
No comment is lost. Comments stay before or after the node they are written
next to, and move with it when it is sorted. A node with a
# prettier-ignore comment before it is written as it is in the source.
Documents that are syntactically correct but break validation rules, for example with fields of unknown types, are formatted. Files with syntax errors are reported with the position of each error and left untouched.
The output differs from that of Prettier in a few cases, where Prettier loses comments or writes documents that cannot be read back:
- control characters in quoted strings, other than tabs, are written as
escapes (
"\r","\u0001") instead of as they are - two comments after nodes that end on the same line are written on two lines; Prettier writes them on one line, which makes the second one part of the first
- a comment on its own line between a description and a definition, or after
the last variable or argument before
), stays there; Prettier moves it into the middle of a line, and moves it again on the next run
Like Prettier, the formatter drops a blank line that follows a comment at the end of a member, and attaches comments written in the middle of a definition, such as between a field name and its type, to the nearest node, from where they can move again on the next run.
| Key | Values | Recommended | Description |
|---|---|---|---|
indent |
1 to 8 | 2 | Number of spaces for one level of nesting. |
line_width |
20 to 1000 | 80 | Line length that groups must fit in to stay on one line. East Asian wide characters count as two columns. |
sort.definitions |
original, grouped, sorted |
original |
grouped puts definitions in this order: schema, directives, scalars, enums, interfaces, object types, input types, unions, operations, fragments. sorted also sorts them by name within their groups, with extensions after the definitions they extend. |
sort.fields |
original, sorted |
original |
Sorts the fields of object types, interfaces and input types, and of their extensions, by name. |
sort.enum_values |
original, sorted |
original |
Sorts enum values by name. |
sort.arguments |
original, sorted |
original |
Sorts the argument definitions of fields and directives by name. |
sort.union_members |
original, sorted |
original |
Sorts the member types of unions by name. |
sort.interfaces |
original, sorted |
original |
Sorts the interfaces that types implement by name. |
sort.directive_locations |
original, sorted |
original |
Sorts the locations of directive definitions by name. |
Without a configuration file, the recommended settings are used. Neither the
recommended nor the original configuration sorts anything, because the order
of definitions and fields shows in introspection results, generated code and
documentation. Selections, arguments and variables of operations are never
sorted, as selections define the order of the response.
Example - 4-space indentation, a line width of 100 characters, and definitions and fields sorted by name
commands:
format:
extends:
- recommended
graphql:
indent: 4
line_width: 100
sort:
definitions: sorted
fields: sortedapigenie format schema/*.graphql --config api-style-guide.yaml