# Swagger 2.0 documents

Source: https://apigenie.pl/docs/reference/cli/format/swagger
Part of the reference of [format](https://apigenie.pl/docs/reference/cli/format.md).
Its other pages: [Layout and YAML styles](https://apigenie.pl/docs/reference/cli/format/styles.md), [Property order](https://apigenie.pl/docs/reference/cli/format/property-order.md), [AsyncAPI documents](https://apigenie.pl/docs/reference/cli/format/asyncapi.md), [Protobuf files](https://apigenie.pl/docs/reference/cli/format/protobuf.md), [GraphQL documents](https://apigenie.pl/docs/reference/cli/format/graphql.md).

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](/docs/reference/cli/format/styles), and
`property_order`, with the [orders](/docs/reference/cli/format/property-order#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

```yaml
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](https://swagger.io/specification/v2/) 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.