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, and the YAML styles of its strings, keys, sequences and mappings. 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 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.

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