Layout and YAML styles
The openapi section of commands.format sets how an OpenAPI document is written: its format, its
indentation, its line endings, where long values are folded, the YAML styles of its strings,
keys, sequences and mappings, and the layout of JSON arrays and objects. The asyncapi and swagger sections take format, indent,
force_array_indent and style with the same values; the layout keys and
style_overrides are for OpenAPI documents.
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).
Layout
The lines of the output:
| 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
The styles of the 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 a YAML input in YAML output.
Since 0.12.0, the flow, block and best-fit array and object styles also
lay out JSON output. flow writes an array or object on one line, with
everything inside it. block and best-fit write one element or member per
line. With object: flow, the whole document is on one line, because its root
is an object. With original, JSON output has one element or member per line,
even for the flow collections of a YAML input. JSON keeps no styles, so a
collection kept on one line would be spread over lines the next time the JSON is
formatted. style_overrides apply to YAML output only.
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.
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: flow