apigenie format
Formats OpenAPI, Swagger 2.0 and AsyncAPI documents, written in JSON or YAML, Protobuf files and GraphQL documents in place, or checks that they are formatted. What it changes comes from the configuration file: the layout and the YAML styles of a document, the order of the properties of every object its specification defines, and what is sorted in Protobuf and GraphQL files. A document keeps its comments and its meaning.
Topics
- Layout and YAML styles: The output format, indentation, line endings and folding, and the YAML styles of strings, keys, sequences and mappings, for a whole document or chosen fields, and the layout of JSON arrays and objects.
- Property order:
original,sortedor a fixed order for each kind of OpenAPI object, and how the objects are recognized in OpenAPI 3.0, 3.1 and 3.2 documents. - AsyncAPI documents: The
asyncapisection, and the objects of AsyncAPI 3 with their recommended order. - Swagger 2.0 documents: The
swaggersection, and the objects of Swagger 2.0 with their recommended order. - Protobuf files: The layout of
.protofiles, and the imports, options, declarations, fields and valuessortcan reorder. - GraphQL documents: The Prettier layout of schemas and operations, where the output differs from Prettier’s, and what
sortcan reorder.
Usage
apigenie format [OPTIONS] FILES...
apigenie format --check [OPTIONS] FILES...
apigenie format --output OUTPUT [OPTIONS] FILE
Without options, the files are formatted with the settings of the project’s configuration file, or the defaults, and written back in their own format:
apigenie format api/openapi.yaml api/events.yaml
--check lists the files that are not formatted instead of writing them, for a CI job, and
--output writes one file elsewhere, in JSON or YAML:
apigenie format --check api/*.yaml
apigenie format api/openapi.yaml --output build/openapi.json
What the formatter changes
The formatter recognizes a file by the root field of its document or by its extension, and reads its settings from the section of the configuration named after it:
| File | Recognized by | Section |
|---|---|---|
| OpenAPI 3.0, 3.1 or 3.2 | the openapi field of the root |
openapi |
| Swagger 2.0 | the swagger field of the root, a string |
swagger |
| AsyncAPI 3 | the asyncapi field of the root |
asyncapi |
| Protobuf (proto3) | the .proto extension |
protobuf |
| GraphQL schema or operations | the .graphql, .graphqls or .gql extension |
graphql |
A JSON or YAML file with none of the three fields is reported
('FILE' is not an OpenAPI, Swagger, AsyncAPI, Protobuf or GraphQL document.) and left untouched;
the other files are still formatted, and the command exits with 2.
In an OpenAPI, Swagger or AsyncAPI document, the formatter changes:
- the indentation, the 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, for the whole document or for chosen fields, and the layout of JSON arrays and objects for the whole document
- the order of the properties of every object the specification defines, at every depth of the document, and of the names in maps such as components, properties or media types
A Protobuf file gets one statement per line, normalized spacing and blank lines between its declarations, and its imports and options sorted; a GraphQL document gets the layout of Prettier. The pages of Protobuf files and GraphQL documents list what else can be sorted.
The formatter never changes what a document means: the output holds the same values as the input, and formatting it again gives the same output. YAML anchors and aliases are the one construct it does not keep: each alias is written as a copy of its anchor’s value, in YAML as in JSON.
A YAML or JSON document is formatted even when it is not a valid document of its specification,
and only a syntax error stops the formatter, unlike lint and diff, which read valid documents
only. A Protobuf or GraphQL file with syntax errors is reported with the position of each error and
left untouched.
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
Options
–config FILE
The configuration file. Without it, the first of apigenie.yaml, apigenie.yml, apigenie.json,
.apigenie.yaml, .apigenie.yml and .apigenie.json found in the current directory or its
parents, up to the root of the git repository, is read. See Configuration.
apigenie format --config api-style-guide.yaml api/openapi.yaml api/events.json
–no-config
Formats with the default settings, without looking for a configuration file.
–check
Checks that the files are formatted, without writing anything. The path of every file that
formatting would change is printed on standard output, one per line, with
N file(s) would be reformatted. on standard error, and the command exits with 1 when there is at
least one. A file whose output format differs from its own (see format)
always counts as a change. Files with syntax errors and unsupported documents are reported as
without --check. Not 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
Writes the result to OUTPUT instead of the input file, and takes one input file. For an OpenAPI,
Swagger or AsyncAPI document, the extension of OUTPUT chooses its format, .json, .yaml or
.yml, so the option converts between JSON and YAML; another extension is an error. A Protobuf or
GraphQL file is written in its own format, whatever the extension. Not with --check.
apigenie format api/openapi.yaml --output build/openapi.json
Exit status
| Status | When |
|---|---|
| 0 | Every file was formatted or, with --check, is already formatted. |
| 1 | With --check, at least one file would change. |
| 2 | A file has syntax errors or is not a supported document (the other files are still formatted or checked), the configuration file is invalid, or the options cannot be used together. |
See the exit statuses shared by the commands.
Configuration
The settings live under commands.format of the configuration file:
extends, and a section per kind of file. Every section is optional, so a configuration can hold
the settings of some kinds only.
| Section | Keys | Page |
|---|---|---|
extends |
A list of the presets recommended and original, applied in order |
Presets |
openapi |
format, indent, force_array_indent, line_width, newline, final_newline, document_marker, style, style_overrides, property_order |
Layout and YAML styles, Property order |
asyncapi |
format, indent, force_array_indent, style, property_order |
AsyncAPI documents |
swagger |
format, indent, force_array_indent, style, property_order |
Swagger 2.0 documents |
protobuf |
indent, sort |
Protobuf files |
graphql |
indent, line_width, sort |
GraphQL documents |
Example - Recommended settings, with CRLF line endings and the descriptions of OpenAPI documents written as literal blocks
commands:
format:
extends:
- recommended
openapi:
newline: crlf
style_overrides:
- fields: [description]
string: literal
Presets
A configuration starts from the defaults: the presets named by extends are applied first, in
order, to every kind of file, then the keys of the sections replace what the presets set.
recommendedindents OpenAPI, Swagger and AsyncAPI documents by 2 spaces, writes their values in thebest-fitstyles and puts the properties of their objects in the fixed orders listed on the pages of the OpenAPI, AsyncAPI and Swagger 2.0 objects, with path templates and response codes sorted. In Protobuf files it sorts imports and options; in GraphQL documents it sorts nothing.originalindents by 2 spaces and keeps the styles and the property order of the input. In Protobuf files and GraphQL documents it sorts nothing.
Without a configuration file, an OpenAPI, Swagger or AsyncAPI document is formatted as with
original: it keeps its format, its styles and its property order, indented by 2 spaces. A Protobuf
or GraphQL file is formatted with the recommended settings.
Unknown keys, unknown object names and values outside their range are errors, reported as
FILE:LINE:COLUMN: POINTER: MESSAGE, for example
apigenie.yaml:5:15: /commands/format/openapi/indent: number is greater than maximum; nothing is
formatted then, and the command exits with 2.
See also
- Configuration: The configuration file, and where it is looked for.
- lint: Checks the content of the documents the formatter lays out.
- GitHub Action: Runs
apigenie format --checkin a workflow.