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 (opens in a new tab) 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 (opens in a new tab), and the output code is of a high quality in terms of developer experience and robustness. See CONTRIBUTING.md (opens in a new tab) to get started
tldr;
Most common functionality used by JSON based APIs should work.
- Great support for
paths
usingapplication/json
request / response bodies - Comprehensive support for most
schema
properties, including json validation stuff likeminLength
, but only forjson
content types. Notable exceptions: readonly
is currently implemented incorrectlydiscriminator
is ignored, butunion
/intersection
types will be generated based onanyOf
/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
Symbol | Meaning |
---|---|
β /π§ | Supported in some way. May be incomplete |
π« | Not supported, likely to be supported eventually |
N/A | Ignored, 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.
Attribute | Supported | Notes |
---|---|---|
openapi | β | Either 3.1.x or 3.0.x is supported |
info | N/A | Ignored |
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 |
externalDocs | N/A | Ignored |
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"
Attribute | Supported | Notes |
---|---|---|
$ref | β | $ref support is robust, and works correctly across multiple input files. |
summary | N/A | Ignored |
description | N/A | Ignored |
Server Object
Currently only used by the client SDKs to generate string literal types for basePath
for intellisense purposes.
Attribute | Supported | Notes |
---|---|---|
url | β | Optionally used to type client SDK basePath configuration |
description | N/A | Ignored |
variables | π« | Not yet supported |
Components Object
Technically you can define any "components" you like, and $ref
s 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.
Attribute | Supported | Notes |
---|---|---|
schemas | β | |
responses | β | |
parameters | β | |
examples | N/A | |
requestBodies | β | |
headers | β | |
securitySchemes | π« | Not yet supported |
links | π« | Not yet supported |
callbacks | π« | Not yet supported |
pathItems | β |
Paths Object
Paths are well supported.
Attribute | Supported | Notes |
---|---|---|
{path} | β |
Path Item Object
All common http methods are supported. Overriding servers
for individual paths is not supported.
Attribute | Supported | Notes |
---|---|---|
summary | N/A | Ignored |
description | N/A | Ignored |
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.
Attribute | Supported | Notes |
---|---|---|
tags | β | Optionally used to split output into multiple files |
summary | N/A | Ignored |
description | N/A | Ignored |
externalDocs | N/A | Ignored |
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.
Attribute | Supported | Notes |
---|---|---|
name | β | |
in | β /π§ | Everything supported apart from "cookie". |
description | N/A | Ignored |
required | β | |
deprecated | N/A | Ignored |
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 | β | |
example | N/A | Ignored |
examples | N/A | Ignored |
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.
Attribute | Supported | Notes |
---|---|---|
description | N/A | Ignored |
content | β /π§ | Only media types of application/json work properly. |
required | β |
Media Type Object
Attribute | Supported | Notes |
---|---|---|
schema | β | |
example | N/A | Ignored |
examples | N/A | Ignored |
encoding | π« | Not yet supported |
Responses Object
Well supported.
Attribute | Supported | Notes |
---|---|---|
default | β | |
{http-status-code} | β |
Response Object
Generally well-supported for application/json
content types.
Attribute | Supported | Notes |
---|---|---|
description | N/A | Ignored |
headers | π« | Not yet supported |
content | β /π§ | Only media types of application/json work properly. |
links | π« | Not yet supported |
Header Object
Attribute | Supported | Notes |
---|---|---|
description | N/A | Ignored |
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.
Attribute | Supported | Notes |
---|---|---|
name | β | Optionally used to split output into multiple files |
description | N/A | Ignored |
externalDocs | N/A | Ignored |
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.
Attribute | Supported | Notes |
---|---|---|
title | N/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 (opens in a new tab) |
writeOnly | π« | Not yet supported |
example | N/A | Ignored |
externalDocs | N/A | Ignored |
deprecated | π« | Not yet supported |
xml | π« | Not yet supported |
Completely unsupported things
The following objects are completely unsupported at this stage.
Encoding Object
Attribute | Supported | Notes |
---|---|---|
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.
Attribute | Supported | Notes |
---|---|---|
\{expression\} | π« |
Link Object
The link object is completely unsupported.
Attribute | Supported | Notes |
---|---|---|
operationRef | π« | |
operationId | π« | |
parameters | π« | |
requestBody | π« | |
description | N/A | |
server | π« |
Discriminator Object
The discriminator object is completely unsupported.
Attribute | Supported | Notes |
---|---|---|
propertyName | π« | |
mapping | π« |
XML Object
The XML object is completely unsupported.
Attribute | Supported | Notes |
---|---|---|
name | π« | |
namespace | π« | |
prefix | π« | |
attribute | π« | |
wrapped | π« |
Security Scheme Object
The security scheme object is completely unsupported.
Attribute | Supported | Notes |
---|---|---|
type | π« | |
description | π« | |
name | π« | |
in | π« | |
scheme | π« | |
bearerFormat | π« | |
flows | π« | |
openIdConnectUrl | π« |
OAuth Flows Object
The oauth flows object is completely unsupported.
Attribute | Supported | Notes |
---|---|---|
implicit | π« | |
password | π« | |
clientCredentials | π« | |
authorizationCode | π« |
OAuth Flow Object
The oauth flow object is completely unsupported.
Attribute | Supported | Notes |
---|---|---|
authorizationUrl | π« | |
tokenUrl | π« | |
refreshUrl | π« | |
scopes | π« |
Security Requirement Object - Patterned Fields
The security requirement object is completely unsupported.
Attribute | Supported | Notes |
---|---|---|
\{name\} | π« |