OverviewCompatibility

Compatibility Tables

This page aims to document which parts of the openapi 3.1.0 specification is supported. It may not be totally complete / accurate, but it should be broadly correct and give you an understanding of what does / doesn’t work.

πŸ’‘

If something you need isn’t supported yet, please raise a Github issue detailing your use-case, and we can work together to get support added / extended.

We will also accept pull requests where implemented functionality follows the OpenAPI specification, and the output code is of a high quality in terms of developer experience and robustness. See CONTRIBUTING.md to get started

tldr;

Most common functionality used by JSON based APIs should work.

  • Great support for paths using application/json request / response bodies
  • Comprehensive support for most schema properties, including json validation stuff like minLength, but only for json content types. Notable exceptions:
  • readonly is currently implemented incorrectly
  • discriminator is ignored, but union / intersection types will be generated based on anyOf / allOf so this isn’t often an issue in practice
  • No support for security schemes, you’ll need to fudge these as header parameters, or implement out-of-band for the specification for now.
  • No support for webhooks / callbacks yet

Legend

SymbolMeaning
βœ…/🚧Supported in some way. May be incomplete
🚫Not supported, likely to be supported eventually
N/AIgnored, unlikely to be used for anything

Root OpenAPI Object

Root object of openapi documents. A βœ… means at least some support for this field - click through to the table for each attribute for further details.

AttributeSupportedNotes
openapiβœ…Either 3.1.x or 3.0.x is supported
infoN/AIgnored
jsonSchemaDialect🚫Not yet supported
serversβœ…Used by client SDK templates
pathsβœ…
webhooks🚫Not yet supported. Emulate by defining as normal paths.
componentsβœ…
security🚫Not yet supported. Implement out of band or using header parameters.
tagsβœ…Optionally used to split output into multiple files
externalDocsN/AIgnored

Sub-objects

Reference Object

Reference objects are supported to be used in place of the actual object definition anywhere in the documents. They can also cross files (and maybe urls - needs testing).

πŸ’‘

It’s recommended to use $ref objects as much as possible. It both promotes re-use, and also allows control over the naming of the type / schema in the generated code.

Example:

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExampleSchema"
AttributeSupportedNotes
$refβœ…$ref support is robust, and works correctly across multiple input files.
summaryN/AIgnored
descriptionN/AIgnored

Server Object

Used by the client SDKs to generate builders for basePath’s and override parameters.

See servers object guide for detailed explanation of how this is handled.

AttributeSupportedNotes
urlβœ…Optionally used to type client SDK basePath configuration
descriptionN/AIgnored
variablesβœ…

Components Object

Technically you can define any β€œcomponents” you like, and $refs to them will work, regardless of if they appear in the official specification.

The table indicates what will actually typically be used for anything right now.

AttributeSupportedNotes
schemasβœ…
responsesβœ…
parametersβœ…
examplesN/A
requestBodiesβœ…
headersβœ…
securitySchemes🚫Not yet supported
links🚫Not yet supported
callbacks🚫Not yet supported
pathItemsβœ…

Paths Object

Paths are well supported.

AttributeSupportedNotes
{path}βœ…

Path Item Object

All common http methods are supported.

AttributeSupportedNotes
summaryN/AIgnored
descriptionN/AIgnored
getβœ…
putβœ…
postβœ…
deleteβœ…
headβœ…
patchβœ…
trace🚫Not yet supported
serversβœ…Used by client SDK templates
parametersβœ…

Operation Object

Most things are supported. It’s recommended you supply an operationId as otherwise one will be generated from the path / http method, which is often overly verbose.

AttributeSupportedNotes
tagsβœ…Optionally used to split output into multiple files
summaryN/AIgnored
descriptionN/AIgnored
externalDocsN/AIgnored
operationIdβœ…Used to generate names on types / methods / interfaces
parametersβœ…
requestBodyβœ…
responsesβœ…
callbacks🚫Not yet supported
deprecated🚫Not yet supported
security🚫Not yet supported
serversβœ…Used by client SDK templates

Parameter Object

Whilst attributes like style and explode are not yet supported, for most common parameter use-cases everything should just work as you’d guess/expect.

AttributeSupportedNotes
nameβœ…
inβœ…/🚧Everything supported apart from β€œcookie”.
descriptionN/AIgnored
requiredβœ…
deprecatedN/AIgnored
allowEmptyValue🚫Use schema minLength: 1 to prevent empty string values in query parameters
style🚫Not yet supported
explode🚫Not yet supported
allowReserved🚫Use schema pattern to emulate
schemaβœ…
exampleN/AIgnored
examplesN/AIgnored
content🚫Not yet supported

Request Body Object

Well-supported for application/json content types. Support for form data, and file uploads, etc planned to come soon.

AttributeSupportedNotes
descriptionN/AIgnored
contentβœ…/🚧Only media types of application/json work properly.
requiredβœ…

Media Type Object

AttributeSupportedNotes
schemaβœ…
exampleN/AIgnored
examplesN/AIgnored
encoding🚫Not yet supported

Responses Object

Well supported.

AttributeSupportedNotes
defaultβœ…
{http-status-code}βœ…

Response Object

Generally well-supported for application/json content types.

AttributeSupportedNotes
descriptionN/AIgnored
headers🚫Not yet supported
contentβœ…/🚧Only media types of application/json work properly.
links🚫Not yet supported

Header Object

AttributeSupportedNotes
descriptionN/AIgnored
schemaβœ…Complex schemas for headers may not work. Stick to string / number if possible.

Tag Object

Tags are only used for code organization purposes, when passing the --grouping-strategy first-tag CLI option.

AttributeSupportedNotes
nameβœ…Optionally used to split output into multiple files
descriptionN/AIgnored
externalDocsN/AIgnored

Schema Object

The majority of attributes that can be specified by schema objects are supported, and accurately match the underlying openapi specification / json schema validation specifications.

Most notable exception is readOnly / writeOnly which are currently implemented incorrectly, planned to be addressed as a breaking change prior to v1.

AttributeSupportedNotes
titleN/A
multipleOfβœ…Applies to type: number
maximumβœ…Applies to type: number
exclusiveMaximumβœ…Applies to type: number
minimumβœ…Applies to type: number
exclusiveMinimumβœ…Applies to type: number
maxLengthβœ…Applies to type: string
minLengthβœ…Applies to type: string
patternβœ…Support for type: string
maxItemsβœ…Applies to type: array
minItemsβœ…Applies to type: array
uniqueItemsβœ…Applies to type: array
maxProperties🚫Not yet supported
minProperties🚫Not yet supported
requiredβœ…Controls whether undefined is allowed for each value in properties
enumβœ…Applies to type: number and type: string
typeβœ…
not🚫Not yet supported
allOfβœ…Produces a intersection type like A & B
oneOfβœ…Produces a union type like A | B
anyOfβœ…Produces a union type like A | B
itemsβœ…Applies to type: array
propertiesβœ…Applies to type: object
additionalPropertiesβœ…/🚧Fairly comprehensive support, produces Record<string, T> or unknown/any (dependent on --ts-allow-any)
formatβœ…/🚧Limited support for format email and date-time
defaultβœ…
nullableβœ…Also supports type: null as an alternative
discriminator🚫Ignored. Union / Intersection types are usd based on anyOf / allOf / oneOf.
readOnly🚫Produces readonly modifiers, but this behavior is incorrect
writeOnly🚫Not yet supported
exampleN/AIgnored
externalDocsN/AIgnored
deprecated🚫Not yet supported
xml🚫Not yet supported

Completely unsupported things

The following objects are completely unsupported at this stage.

Encoding Object

AttributeSupportedNotes
contentType🚫Not yet supported
headers🚫Not yet supported
style🚫Not yet supported
explode🚫Not yet supported
allowReserved🚫Not yet supported

Callback Object

The callback object is completely unsupported.

AttributeSupportedNotes
\{expression\}🚫

The link object is completely unsupported.

AttributeSupportedNotes
operationRef🚫
operationId🚫
parameters🚫
requestBody🚫
descriptionN/A
server🚫

Discriminator Object

The discriminator object is completely unsupported.

AttributeSupportedNotes
propertyName🚫
mapping🚫

XML Object

The XML object is completely unsupported.

AttributeSupportedNotes
name🚫
namespace🚫
prefix🚫
attribute🚫
wrapped🚫

Security Scheme Object

The security scheme object is completely unsupported.

AttributeSupportedNotes
type🚫
description🚫
name🚫
in🚫
scheme🚫
bearerFormat🚫
flows🚫
openIdConnectUrl🚫

OAuth Flows Object

The oauth flows object is completely unsupported.

AttributeSupportedNotes
implicit🚫
password🚫
clientCredentials🚫
authorizationCode🚫

OAuth Flow Object

The oauth flow object is completely unsupported.

AttributeSupportedNotes
authorizationUrl🚫
tokenUrl🚫
refreshUrl🚫
scopes🚫

Security Requirement Object - Patterned Fields

The security requirement object is completely unsupported.

AttributeSupportedNotes
\{name\}🚫