CLI

Formats JSON and YAML files containing OpenAPI schemas.

Usage

apigenie format [OPTIONS] FILES

Description

This command formats JSON and YAML files containing OpenAPI schemas. This formatting helps to:

  • maintain a consistent style for your OpenAPI schemas
  • enhance readability of the schemas
  • facilitate collaboration on schemas among multiple developers

API Genie formatter works with all supported file formats. However, it is important to note that it’s not a generic JSON/YAML parser.

The formatter can process partially invalid schemas. It fails only when it encounters JSON or YAML syntax error. This is different from commands like lint or diff, which need valid OpenAPI schemas.

Currently, the formatter can change the following aspects of input schemas:

  • Indentation size
  • Order or properties for objects defined by OpenAPI specification

Specifying property order

Formatter command can be configured to list properties of OpenAPI objects in specific order. This greatly helps to improve the readability of OpenAPI schemas.

Below are supported modes of ordering properties of schema objects:

  • original - list properties in the same order as in input file. This is the default behaviour.
  • sorted - sort properties alphabetically
  • custom - users can define property order in the configuration file

Each mode can be useful in specific situations. For example, original mode is useful when modifying existing schemas to avoid excessive changes. Sorted mode is a natural order for elements like path items or shared schemas. Finally, custom order allows users to define a specific order for properties within schema objects, which can be beneficial for request/response bodies and operations where placing summary and description properties at the beginning improves readability.

Property mode can be configured

  • Globally (default) for all schema objects
  • Per schema object type

Example - Preserve original property order for all schema objects

commands:
  format:
    openapi:
      property_order:
        default: original

Example - Sort all path items within Paths objects alphabetically

commands:
  format:
    openapi:
      property_order:
        paths: sorted

Example - Specify custom property order for Operation objects

commands:
  format:
    openapi:
      property_order:
        operation:
          # place summary and description at the beginning, to help
          # understand operation's purpose
          - summary
          - description
          - tags
          - operationId
          - externalDocs
          - deprecated
          - parameters
          - requestBody
          - responses
          - callbacks
          - security
          - servers

Properties not explicitly listed in the configuration for a specific schema object type will be placed after the listed ones, sorted alphabetically.

Example

If the configuration for the Contact object looks like:

commands:
  format:
    openapi:
      property_order:
        contact:
          - name
          - url
          - email

and the actual contact data before formatting looks like:

openapi:
  info:
    contact:
      x-team: awesome
      name: You
      email: you@example.com
      url: your.site
      x-audience: internal
      x-stability: stable
  ...

formatting it will change it to:

openapi:
  info:
    contact:
      name: You
      url: your.site
      email: you@example.com
      x-audience: internal
      x-team: awesome
      x-stability: stable
  ...

Options

Without options, formatter formats input file(-s) using default configuration. The resulting content is written back into input files, without changing their format.

apigenie format input1.yaml input2.json

—config FILE

Optional path to the configuration file. If not specified, the default configuration is used. For details, see the configuration section.

apigenie format --config api-style-guide.yaml input1.yaml input2.json

—output OUTPUT

Optional path to the output file. If not specified, resulting content is written to the input file.

If this option is given, formatter processes only a single file at a time.

Note that the output format is determined by this file’s extension. So this can be used to convert between JSON and YAML representations.

apigenie format input.yaml --output output.json

Configuration

Formatter stores its configuration under the #/commands/format/openapi key in the configuration file. See the global configuration section to understand how this file is structured.

indent

This key stores number of whitespace characters used to indent by one level.

property_order

This section stores custom property orders for OpenAPI schema objects. Valid keys in this section is either default or name of schema object written in camelCase.

property_order.default

Sets the default property order. Valid values are sorted and original. The default value is original.

property_order.openapi

Defines property order for the OpenAPI object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        openapi:
          - openapi
          - info
          - jsoSchemaDialect
          - servers
          - paths
          - webhooks
          - components
          - security
          - tags
          - externalDocs

property_order.info

Defines property order for the Info object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        info:
          - title
          - summary
          - description
          - version
          - termsOfService
          - contact
          - license

property_order.contact

Defines property order for the Contact object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        contact:
          - name
          - url
          - email

property_order.license

Defines property order for the License object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        license:
          - name
          - identifier
          - url

property_order.server

Defines property order for the Server object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        server:
          - url
          - description
          - variables

property_order.serverVariable

Defines property order for the Server Variable object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        serverVariable:
          - description
          - default
          - enum

property_order.paths

Defines property order for the Paths object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        paths: sorted

property_order.pathItem

Defines property order for the Path Item object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        pathItem:
          - summary
          - description
          - parameters
          - get
          - post
          - put
          - patch
          - delete
          - options
          - head
          - trace
          - servers

property_order.operation

Defines property order for the Operation object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        operation:
          - tags
          - summary
          - operationId
          - description
          - externalDocs
          - deprecated
          - parameters
          - requestBody
          - responses
          - callbacks
          - security
          - servers

property_order.components

Defines property order for the Components object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        components:
          - schemas
          - responses
          - parameters
          - requestBodies
          - headers
          - pathItems
          - securitySchemes
          - links
          - callbacks
          - examples

property_order.externalDocumentation

Defines property order for the External Documentation object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        externalDocumentation:
          - description
          - url

property_order.parameter

Defines property order for the Parameter object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        parameter:
          - name
          - in
          - description
          - required
          - deprecated
          - style
          - allowEmptyValue
          - explode
          - allowReserved
          - schema
          - content
          - example
          - examples

property_order.requestBody

Defines property order for the Request Body object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        requestBody:
          - description
          - required
          - content

property_order.mediaType

Defines property order for the Media Type object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        mediaType:
          - schema
          - encoding
          - example
          - examples

property_order.encoding

Defines property order for the Encoding object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        encoding:
          - contentType
          - style
          - headers
          - explode
          - allowReserved

property_order.responses

Defines property order for the Responses object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        responses: sorted

property_order.response

Defines property order for the Response object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        response:
          - description
          - headers
          - content
          - links

property_order.example

Defines property order for the Example object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        example:
          - summary
          - description
          - value
          - externalValue

Defines property order for the Link object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        link:
          - description
          - server
          - operationRef
          - operationId
          - parameters
          - requestBody

property_order.header

Defines property order for the Header object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        header:
          - name
          - description
          - required
          - deprecated
          - allowEmptyValue
          - explode
          - allowReserved
          - schema
          - content
          - example
          - examples

property_order.tag

Defines property order for the Tag object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        tag:
          - name
          - description
          - externalDocs

property_order.reference

Defines property order for the Reference object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        reference:
          - $ref
          - summary
          - description

property_order.schema

Defines property order for the Schema object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        schema:
          - title
          - description
          - type
          - format
          - const
          - enum
          - minimum
          - exclusiveMinimum
          - maximum
          - exclusiveMaximum
          - multipleOf
          - minLength
          - maxLength
          - pattern
          - items
          - prefixItemCount
          - minItems
          - maxItems
          - uniqueItems
          - required
          - properties
          - patternProperties
          - propertyNames
          - additionalProperties
          - minProperties
          - maxProperties
          - allOf
          - oneOf
          - anyOf
          - not
          - discriminator
          - xml
          - externalDocs

property_order.discriminator

Defines property order for the Discriminator object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        discriminator:
          - propertyName
          - mapping

property_order.xml

Defines property order for the XML object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        xml:
          - name
          - namespace
          - prefix
          - attribute
          - wrapped

property_order.securityScheme

Defines property order for the Security Scheme object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        securityScheme:
          - name
          - description
          - type
          - in
          - scheme
          - bearerFormat
          - flows
          - openIdConnectUrl

property_order.oauthFlows

Defines property order for the OAuthFlows object.

Its value can be sorted, original or an array of property names in desired order.

Example - Recommended property order for best readability

commands:
  format:
    openapi:
      property_order:
        oauthFlows:
          - implicit
          - password
          - clientCredentials
          - authorizationCode