Skip to content

Latest commit

 

History

History
327 lines (241 loc) · 9.77 KB

openapi3-support.md

File metadata and controls

327 lines (241 loc) · 9.77 KB

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

  • Primitive data types, integer, number, string and boolean.
  • Any format will be displayed.
  • 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

  • name
  • url
  • email

License object

  • name
  • url

Server 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

  • 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

Media Type object

Encoding object

  • contentType
  • headers
  • style
  • explode
  • allowReserved

Responses object

Response object

Callback object

Example object

  • summary
  • description
  • value
  • externalValue

Link object

  • 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

  • propertyName
  • mapping

XML object

  • name
  • namespace
  • prefix
  • attribute
  • wrapped
  • type
    • apiKey
    • http
    • oauth2
    • openIdConnect
  • description
  • name
  • in
  • scheme
  • bearerFormat
  • flows
  • openIdConnectUrl

OAuth Flow object

  • authorizationUrl
  • tokenUrl
  • refreshUrl
  • scopes
  • oauth2
  • openIdConnect
  • "other"

No extension properties are supported at this time.