Swagger 2.0 documents

A Swagger 2.0 document is recognized by the swagger field of its root and formatted with the swagger section of commands.format. The section takes format, indent, force_array_indent and style, with the values described in Layout and YAML styles, and property_order, with the orders of the OpenAPI section and the objects below. The presets of extends apply to Swagger documents as to the others.

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
          - responses

Objects

The keys of property_order are default and the names of the objects of Swagger 2.0 below. Each key takes sorted, original or an array of property names; the last column is the order of the recommended preset.

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.