openapi3-support.md

OpenAPI v3 support

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

• All description fields support CommonMark.

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

• openapi
• info
• servers
• paths
• components
• security
• tags
• externalDocs

Info object

• title
• description
• termsOfService
• contact
• license
• version

Contact

• name
• url
• email

License object

• name
• url

Server object

• url
• description
• variables

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.

• schemas
• responses
• parameters
• examples
• requestBodies
• headers
• securitySchemes
• links
• callbacks

Paths object

• pathItem

Path Item object

• $ref
• summary
• description
• get
• put
• post
• delete
• options
• head
• patch
• trace
• servers
• parameters

Operation object

• tags
• summary
• description
• externalDocs
• operationId
• parameters
• requestBody
• responses
• callbacks
• deprecated
• security
• servers

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

• description
• content
• required

Media Type object

• schema
• example
• examples
• encoding

Encoding object

• contentType
• headers
• style
• explode
• allowReserved

Responses object

• response

Response object

• description
• headers
• content
• links

Callback object

• expression

Example object

• summary
• description
• value
• externalValue

Link object

• operationRef
• operationId
• parameters
• requestBody
• description
• server

Header object

See parameter object.

Tag object

• name
• description
• externalDocs

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

• nullable
• discriminator
• readOnly
• writeOnly
• xml
• externalDocs
• example
• deprecated

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

• implict
• password
• clientCredentials
• authorizationCode

OAuth Flow object

• authorizationUrl
• tokenUrl
• refreshUrl
• scopes

Security Requirement object

• oauth2
• openIdConnect
• "other"

Specification Extensions

No extension properties are supported at this time.