OpenAPI v3 support

July 8, 2021 ยท View on GitHub

Tracking: v3.0.0

This document originated at https://github.com/temando/open-api-renderer/blob/master/docs/open-api-v3-support.md

This document outlines this project's support for visualising the OpenAPI V3 specification. Content is outlined in the same order as the original specification to make reading as quick (and familiar) as possible.

General

Data Types

  • Primitive data types, integer, number, string and boolean.
  • Any format will be displayed.

Rich Text Formatting

Relative References in URLs

  • Relative references are resolved using the URLs defined in the Server Object as a Base URI.
  • Relative references used in $ref are processed as per JSON Reference.

Schema

OpenAPI object

Info object

Contact

  • name
  • url
  • email

License object

  • name
  • url

Server object

Server Variable object

  • enum
  • default
  • description

Components object

This is supported by default as all $ref are dereferenced before the definition is visualised. As per spec, Components have no impact on visualising the API reference, they are simply a placeholder for reusable objects.

Paths object

Path Item object

Operation object

External Documentation object

  • description
  • url

Parameter object

  • name
  • in
    • query
    • header
    • path
    • cookie
  • description
  • required
  • deprecated
  • allowEmptyValue

schema extensions

  • style
    • matrix
    • label
    • form
    • simple
    • spaceDelimited
    • pipeDelimited
    • deepObject
  • explode
  • allowReserved
  • schema
  • example
  • examples
  • content

Request Body object

Media Type object

Encoding object

  • contentType
  • headers
  • style
  • explode
  • allowReserved

Responses object

Response object

Callback object

Example object

  • summary
  • description
  • value
  • externalValue
  • operationRef
  • operationId
  • parameters
  • requestBody
  • description
  • server

Header object

See parameter object.

Tag object

Reference object

  • $ref

Schema object

The Schema object describes several properties that are shared from JSON Schema, deviations from JSON Schema, or in addition to JSON Schema. The following descibes this project's support for these properties.

Properties

The following properties are supported, and implemented according to the JSON Schema Validation spec:

  • multipleOf
  • maximum
  • exclusiveMaximum
  • minimum
  • exclusiveMinimum
  • maxLength
  • minLength
  • pattern
  • maxItems
  • minItems
  • uniqueItems
  • maxProperties
  • minProperties
  • format
  • required
  • enum

Adjusted JSON Schema Properties

The OpenAPI specification also supports several additional properties from JSON Schema, with some adjustments. This project attempts to honor these adjustments, with any exceptions outlined below:

  • type - Value may be an array, multiple types are supported.
  • allOf
  • oneOf
  • anyOf
  • not
  • items
  • properties
  • additionalProperties
  • description
  • format
  • default

Fixed Fields

Discriminator object

  • propertyName
  • mapping

XML object

  • name
  • namespace
  • prefix
  • attribute
  • wrapped

Security Scheme object

  • type
    • apiKey
    • http
    • oauth2
    • openIdConnect
  • description
  • name
  • in
  • scheme
  • bearerFormat
  • flows
  • openIdConnectUrl

OAuth Flows object

OAuth Flow object

  • authorizationUrl
  • tokenUrl
  • refreshUrl
  • scopes

Security Requirement object

  • oauth2
  • openIdConnect
  • "other"

Specification Extensions

No extension properties are supported at this time.