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✅Server URLs cam be usd to type client SDK base paths
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

Currently only used by the client SDKs to generate string literal types for basePath for intellisense purposes.

AttributeSupportedNotes
url✅Optionally used to type client SDK basePath configuration
descriptionN/AIgnored
variables🚫Not yet supported

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. Overriding servers for individual paths is not supported.

AttributeSupportedNotes
summaryN/AIgnored
descriptionN/AIgnored
get✅
put✅
post✅
delete✅
head🚫Not yet supported
patch✅
trace🚫Not yet supported
servers🚫Not yet supported
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🚫Not yet supported

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\}🚫

Link Object

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\}🚫
AboutQuick Start