# format Source: https://apigenie.pl/docs/reference/cli/format Formats JSON and YAML files containing OpenAPI, Swagger 2.0 or AsyncAPI schemas, Protobuf (`.proto`) files and GraphQL (`.graphql`, `.graphqls`, `.gql`) files. ## Usage ```sh apigenie format [OPTIONS] FILES ``` ## Description 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](#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](#protobuf-configuration)), and files with the `.graphql`, `.graphqls` or `.gql` extension as GraphQL documents (see [GraphQL configuration](#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 ```yaml commands: format: openapi: property_order: default: original ``` **Example** - Sort all path items within `Paths` objects alphabetically ```yaml commands: format: openapi: property_order: paths: sorted ``` **Example** - Specify custom property order for `Operation` objects ```yaml 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 - servers ``` Properties 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: ```yaml commands: format: openapi: property_order: contact: - name - url - email ``` and the actual contact data before formatting looks like: ```yaml 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: ```yaml 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. ```sh 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](#configuration) section. ```sh 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](#swagger-configuration)) always counts as a change. Files with syntax errors and unsupported documents are reported as without `--check`. Cannot be combined with `--output`. ```sh 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. ```sh 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. ```sh 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. ```sh apigenie format input.yaml --output output.json ``` ## Exit 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](/docs/reference/cli/overview#exit-status) 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](#asyncapi-configuration)). Swagger 2.0 documents use the `#/commands/format/swagger` key (see [Swagger configuration](#swagger-configuration)). Protobuf files use the `#/commands/format/protobuf` key (see [Protobuf configuration](#protobuf-configuration)), and GraphQL files the `#/commands/format/graphql` key (see [GraphQL configuration](#graphql-configuration)). All sections are optional. See the [global configuration](/docs/reference/cli/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 ```yaml commands: format: extends: - recommended openapi: newline: crlf style_overrides: - fields: [description] string: literal ``` ### format 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](#property_order) of the objects holding them), or by both, and sets one or more of `string`, `array` and `object`, with the values of [style](#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 ```yaml commands: format: openapi: style_overrides: - fields: [description] string: literal - fields: [tags] objects: [operation] array: flow - fields: [required] objects: [schema] array: flow ``` ### property_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 ```yaml commands: format: openapi: property_order: componentNames: sorted ``` ### OpenAPI 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`, `unevaluatedProperties` and `contentSchema`, and under the `itemSchema` of a 3.2 media type. Boolean schemas are left as they are. - Path items and operations are recognized in `paths`, `webhooks`, the `callbacks` of operations at any depth and in components, and so are 3.2 `query` operations and `additionalOperations`. - Headers, media types, encodings (also 3.2 `prefixEncoding` and `itemEncoding`) and examples are recognized wherever the specification allows them, including the content and examples of headers. - Example payloads, `default`, `const` and `enum` values and the values of `x-` fields are data: they are never formatted as OpenAPI objects, and their keys follow the `exampleValue` and `extension` orders. 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 ```yaml commands: format: extends: - recommended asyncapi: indent: 2 property_order: channels: sorted operation: - action - channel - summary - description - messages - reply ``` Keys of the `property_order` section are `default` or one of the following names of [AsyncAPI 3 objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0). 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 ```yaml commands: format: extends: - recommended swagger: format: json indent: 2 property_order: definitions: sorted operation: - operationId - summary - tags - parameters - responses ``` Keys of the `property_order` section are `default` or one of the following names of [Swagger 2.0 objects](https://swagger.io/specification/v2/). 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 ```yaml commands: format: extends: - recommended protobuf: indent: 4 sort: declarations: grouped fields: number enum_values: number ``` ```sh apigenie format api/store/v1/*.proto --config api-style-guide.yaml ``` ## GraphQL 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](https://prettier.io): 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, `implements` lists 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 the `query` keyword 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 ```yaml commands: format: extends: - recommended graphql: indent: 4 line_width: 100 sort: definitions: sorted fields: sorted ``` ```sh apigenie format schema/*.graphql --config api-style-guide.yaml ```