OpenAPI Compatibility Chart
This OpenAPI Compatibility Chart aims to document every part of the OpenAPI Specification that we do and don't support, as well as any quirks that might be present that you should be aware of.
We currently support OpenAPI through v3.1.0. For Swagger 2.0 support we use a tool called swagger2openapi that upconverts Swagger definitions to OpenAPI 3.0.
Unless mentioned otherwise, all
description
properties that we support are run through our Markdown engine: RDMD
OpenAPI Object
đ Specification Link
openapi
- We currently support everything up through
3.1.0
.
- We currently support everything up through
info
â Info ObjectjsonSchemaDialect
jsonSchemaDialect
is new to OpenAPI 3.1. See JSON Schema Dialects for a list of dialects that we support. â
servers
â Server Objectpaths
â Paths Objectwebhooks
- Map containing Path Item Object and/or Reference Object- OpenAPI definitions can contain a mix of
paths
andwebhooks
â as of January 2024, we support both. â
- OpenAPI definitions can contain a mix of
components
â Components Objectsecurity
â Security Requirement Object- We support both global and operation-specific security requirements. â
tags
â Tag ObjectexternalDocs
â External Documentation Object
Info Object
đ Specification Link
title
âsummary
âsummary
is new to OpenAPI 3.1.- This value is surfaced in the API Info table on the Getting Started page.
description
â- This value is surfaced in the API Info table on the Getting Started page.
termsOfService
â- This value is surfaced in the API Info table on the Getting Started page.
contact
â- See Contact Object for more details.
- This object is surfaced in the API Info table on the Getting Started page.
license
â- See License Object for more details.
- This object is surfaced in the API Info table on the Getting Started page.
version
â- For certain OpenAPI definition upload methods, we use this value to determine what version of your docs to place your API definition. See Versions for more information on docs versions. Below, we go over the different upload methods:
- When uploading via
rdme
, this value is ignored by default. To use this value, you can pass theuseSpecVersion
flag. - When uploading via the API, this value is used only if the
x-readme-version
request header is omitted. - This value is ignored by default in file uploads.
- When uploading via
- For certain OpenAPI definition upload methods, we use this value to determine what version of your docs to place your API definition. See Versions for more information on docs versions. Below, we go over the different upload methods:
Contact Object
đ Specification Link
This object is surfaced in the API Info table on the Getting Started page.
name
âurl
âemail
â
License Object
đ Specification Link
This object is surfaced in the API Info table on the Getting Started page.
name
âidentifier
âidentifier
is new to OpenAPI 3.1.
url
â
Server Object
đ Specification Link
url
âdescription
âvariables
â- See Server Variable Object for more details.
Server Variable Object
đ Specification Link
enum
âdefault
âdescription
â
Components Object
đ Specification Link
With the exception of
securitySchemes
, all components that can be loaded as a$ref
pointer are dereferenced prior to rendering.
schemas
â Schema Objectresponses
â Response Objectparameters
â Parameter Objectexamples
â Example ObjectrequestBodies
â Request Body Objectheaders
â Header ObjectsecuritySchemes
â Security Scheme Objectlinks
â Link Objectcallbacks
â Callback ObjectpathItems
â Path Item ObjectpathItems
is new with OpenAPI 3.1.
Paths Object
đ Specification Link
We support the Path Object because we wouldn't offer an API Reference without them. đ
Path Item Object
đ Specification Link
$ref
â- All
$ref
pointers are dereferenced prior to rendering.
- All
summary
âdescription
âget
âput
âpost
âdelete
âoptions
âhead
âpatch
âtrace
âservers
â- We currently do not support
servers
declarations at the Path Item level. See Server Object for more details.
- We currently do not support
parameters
â
Operation Object
đ Specification Link
tags
âsummary
âdescription
âexternalDocs
â- See External Documentation Object for more details.
operationId
âparameters
â- See Parameter Object for more details.
requestBody
â- See Request Body Object for more details.
responses
â- See Responses Object for more details.
callbacks
â- See Callback Object for more details.
deprecated
âsecurity
â- See Security Requirement Object for more details.
servers
â- We currently do not support
servers
declarations at the Operation level. See Server Object for more details.
- We currently do not support
External Documentation Object
đ Specification Link
We currently only surface the
External Documentation Object
within the Tag Object of your documentation.
description
âurl
â
Parameter Object
đ Specification Link
name
âin
âdescription
ârequired
âdeprecated
âallowEmptyValue
â- To add an empty value into our API Explorer you must first type in something and then delete it.
style
âexplode
âallowReserved
âschema
â- See Schema Object for more details.
example
âexamples
âcontent
â
Style Values
đ Specification Link
Support for parameter style
serialization:
style | Data type | explode | Path | Query, multipart/form-data | Cookie | Header |
---|---|---|---|---|---|---|
matrix | primitive | true | â | - | - | - |
matrix | primitive | false | â | - | - | - |
matrix | array | true | â | - | - | - |
matrix | array | false | â | - | - | - |
matrix | object | true | â | - | - | - |
matrix | object | false | â | - | - | - |
label | primitive | true | â | - | - | - |
label | primitive | false | â | - | - | - |
label | array | true | â | - | - | - |
label | array | true | â | - | - | - |
label | object | true | â | - | - | - |
label | object | true | â | - | - | - |
form | primitive | true | - | â | â | |
form | primitive | false | - | â | â | |
form | array | true | - | â | â | |
form | array | false | - | â | â | |
form | object | true | - | â | â | |
form | object | false | - | â | â | |
simple | array | true | â | - | - | â |
simple | array | false | â | - | - | â |
spaceDelimited | array | true | - | â | - | - |
spaceDelimited | array | false | - | â | - | - |
spaceDelimited | object | true | - | â | - | - |
spaceDelimited | object | false | - | â | - | - |
spaceDelimited | query | true | â ïž | â ïž | â ïž | â ïž |
spaceDelimited | query | false | â ïž | â ïž | â ïž | â ïž |
pipeDelimited | array | true | - | â | - | - |
pipeDelimited | array | false | - | â | - | - |
pipeDelimited | object | true | - | â | - | - |
pipeDelimited | object | false | - | â | - | - |
pipeDelimited | query | true | â ïž | â ïž | â ïž | â ïž |
pipeDelimited | query | false | â ïž | â ïž | â ïž | â ïž |
deepObject | object | true | - | â
(including arrays of objects, serialized using the qs module) | - | - |
deepObject | object | false | - | â | - | - |
spaceDelimited
andpipeDelimited
support onquery
andform-data
parameters, while new to OpenAPI 3.1, is currently untested on our platform.
Request Body Object
đ Specification Link
description
âcontent
â ïž- Though we support
content
, the API Reference only supports one Media Type at a time; so if you have acontent
declaration that has two Media Types we'll use either the first out of the list or whichever is JSON-compatible.
- Though we support
required
â
Media Type Object
đ Specification Link
schema
âexample
âexamples
âencoding
â ïž- We only support
encoding
formultipart/form-data
media types.
- We only support
Encoding Object
đ Specification Link
We only support the
Encoding Object
onmultipart/form-data
media types.
contentType
âheaders
âstyle
â ïž- We support the
style
parameter formultipart/form-data
media types. See the style support list for more details.
- We support the
explode
â ïž- We support the
explode
parameter formultipart/form-data
media types. See the style support list for more details.
- We support the
allowReserved
â
Responses Object
đ Specification Link
For Responses we support default
, blanket 1XX
, 2XX
, 3XX
, 4XX
, and 5XX
statuses, as well as all HTTP status codes that are listed within with IANA Status Code Registry.
Any HTTP status code that is used but not listed below will be shown but internally treated as a general
<number>XX
variant.
Code | Description |
---|---|
1XX | Informational |
100 | Continue |
101 | Switching Protocols |
102 | Processing |
103 | Early Hints |
2XX | Success |
200 | OK |
201 | Created |
202 | Accepted |
203 | Non-Authoritative Information |
204 | No Content |
205 | Reset Content |
206 | Partial Content |
207 | Multi-Status |
208 | Already Reported |
218 | This is fine |
226 | IM Used |
3XX | Redirection |
300 | Multiple Choices |
301 | Moved Permanently |
302 | Found |
303 | See Other |
304 | Not Modified |
305 | Use Proxy |
306 | Switch Proxy |
307 | Temporary Redirect |
308 | Permanent Redirect |
4XX | Client Error |
400 | Bad Request |
401 | Unauthorized |
402 | Payment Required |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
406 | Not Acceptable |
407 | Proxy Authentication Required |
408 | Request Timeout |
409 | Conflict |
410 | Gone |
411 | Length Required |
412 | Precondition Failed |
413 | Payload Too Large |
414 | URI Too Long |
415 | Unsupported Media Type |
416 | Range Not Satisfiable |
417 | Expectation Failed |
418 | I'm a teapot |
419 | Page Expired |
420 | Enhance Your Calm |
421 | Misdirected Request |
422 | Unprocessable Entity |
423 | Locked |
424 | Failed Dependency |
425 | Too Early |
426 | Upgrade Required |
428 | Precondition Required |
429 | Too Many Requests |
430 | Request Header Fields Too Large |
431 | Request Header Fields Too Large |
440 | Login Time-out |
444 | No Response |
449 | Retry With |
450 | Blocked by Windows Parental Controls |
451 | Unavailable For Legal Reasons |
494 | Request Header Too Large |
495 | SSL Certificate Error |
496 | SSL Certificate Required |
497 | HTTP Request Sent to HTTPS Port |
498 | Invalid Token |
499 | Client Error |
5XX | Server Error |
500 | Internal Server Error |
501 | Not Implemented |
502 | Bad Gateway |
503 | Service Unavailable |
504 | Gateway Timeout |
505 | HTTP Version Not Supported |
506 | Variant Also Negotiates |
507 | Insufficient Storage |
508 | Loop Detected |
509 | Bandwidth Limit Exceeded |
510 | Not Extended |
511 | Network Authentication Required |
520 | Web Server Returned an Unknown Error |
521 | Web Server Is Down |
522 | Connection Timed Out |
523 | Origin Is Unreachable |
524 | A Timeout Occurred |
525 | SSL Handshake Failed |
526 | Invalid SSL Certificate |
527 | Railgun Error |
529 | Site is Overloaded |
530 | Site is Frozen |
598 | Network Read Timeout Error |
Response Object
đ Specification Link
description
âheaders
â- See Header Object for more details.
content
â- See Media Type Object for more details.
links
â- See Link Object for more details.
Callback Object
đ Specification Link
As a Callback Object
is a container for a Path Item Object, see the Path Item Object for our list of supported components.
Note that we do not currently support making API requests to callback endpoints, they are purely rendered as documentation.
Example Object
đ Specification Link
summary
â- If this is not supplied, when rendering Request Body examples we will set this to "Request Example".
description
â- We currently do not surface example descriptions anywhere.
value
âexternalValue
â- We currently do not surface external example values anywhere.
Link Object
đ Specification Link
We currently do not support the
Link Object
.
operationRef
operationId
parameters
requestBody
description
server
- See Server Object for more details.
Header Object
đ Specification Link
Where we support
headers
, and the Header Object, we support everything for headers that we support within the Parameter Object. See Parameter Object for more information.
Tag Object
đ Specification Link
name
âdescription
âexternalDocs
â- See External Documentation Object for more details.
When handling tags not only do we ingest them when you upload an OpenAPI definition to create Categories, Pages and Subpages, but we also render tags on your API Reference like so:
Reference Object
đ Specification Link
Prior to rendering your API documentation all $ref
pointers are dereferenced. Additionally, as of OpenAPI 3.1, you can include summary
and description
fields in addition to the $ref
pointer, which will override the summary
and description
fields of the referenced component. Everything else will be fully deferenced.
Relative schemas ($ref: "Pet.json"
) and URL references ($ref: "https://example.com/Pet"
) are not supported on ReadMe and will be rejected on upload. If your schema uses relative schemas or URL references you can instead upload your API definition via rdme
and that will bundle all the necessary schemas together into a single payload acceptable for our API.
Note that we currently struggle to handle recursive and circular reference objects. Under certain circumstances in parameters and request bodies we're able to handle a circular reference itâs within an array (like an array of objects).
Schema Object
đ Specification Link
Properties
additionalProperties
â ïž- Though JSON Schema Specification Wright Draft 00 specifies that when
additionalProperties
is not present, defaults totrue
, ReadMe defaults tofalse
for a cleaner UI. If you wish to allow users to add additional properties you should explicitly set this totrue
.
- Though JSON Schema Specification Wright Draft 00 specifies that when
allOf
âanyOf
âconst
âdefault
âdescription
âenum
âexclusiveMaximum
âexclusiveMinimum
âformat
â- See Data Types for a list of formats that we support.
items
âmaximum
âmaxItems
âmaxLength
âmaxProperties
âminimum
âminItems
âminLength
âminProperties
âmultipleOf
ânot
âoneOf
âpattern
âpatternProperties
âproperties
ârequired
âtitle
âtitle
in a schema associated with a Parameter or Request Body OAS section is prioritized over that section'sname
property when displaying a label to an end user.
type
â ïž- We support general and mixed
type
declarations however our API Explorer form system does not support settingnull
data for mixed non-primitive and non-boolean nullable schemas. For example,['boolean', 'null']
and['string', 'null']
are supported but['array', 'null']
and['object', 'null']
are not.
- We support general and mixed
uniqueItems
â
Fixed Fields
deprecated
âdiscriminator
â- See Discriminator Object for more details.
example
âexternalDocs
â- See External Documentation Object for more details.
nullable
â ïž- Our API Explorer form system does not support setting null data for
array
,object
, orboolean
types.
- Our API Explorer form system does not support setting null data for
readOnly
â- Properties marked as
readOnly: true
are only rendered in the Response Schema section.
- Properties marked as
writeOnly
â- Properties marked as
writeOnly: true
are only rendered in the Request section.
- Properties marked as
xml
â- See XML Object for more details.
JSON Schema Dialects
Unicode regular expressions are only supported with OpenAPI v3.1.x documents and JSON Schema v2020-12. If no JSON Schema dialects are specified, we adhere to the OAS and default to v2020-12 for all OpenAPI v3.1.x documents.
We support the following JSON Schema dialects:
Data Types
đ Specification Link
We support a number of different data types and formats:
Type | Format | Comments |
---|---|---|
boolean | ||
integer | ||
integer | int8 | |
integer | int16 | |
integer | int32 | |
integer | int64 | |
integer | uint8 | |
integer | uint16 | |
integer | uint32 | |
integer | uint64 | |
number | ||
number | float | |
number | double | |
string | ||
string | binary | Will render out a file input. |
string | blob | Will render out a textarea. |
string | byte | ⥠|
string | date | â |
string | dateTime | â |
string | date-time | â |
string | duration | |
string | html | Will render out a textarea. ⥠|
string | json | Will render out a textarea. ⥠|
string | password | Will render out a password field to mask all input. |
string | timestamp | |
string | uri | ⥠|
string | url | ⥠|
string | uuid | ⥠|
â We do not render a date picker for date
and date-time
due to the lack of wide browser support for datetime-local and RFC 3339.
⥠We do not perform any validation on this value to ensure the value remains unchanged.
Discriminator Object
đ Specification Link
propertyName
âmapping
â
XML Object
đ Specification Link
We currently do not support the
XML Object
.
name
namespace
prefix
attribute
wrapped
Security Scheme Object
đ Specification Link
type
â ïž- We do not support the
openIdConnect
security type. - We do not support the
mutualTLS
security type that was introduced in OpenAPI 3.1
- We do not support the
description
âname
âin
âscheme
âbearerFormat
â ïž- The OpenAPI Specification specifies that this describes how the bearer formatted but since we do not support OAuth Flows that would format the bearer, we currently ignore this.
flows
â- We currently do not support traditional OAuth flows for generating tokens, instead preferring you use our JWT authentication flow for supplying us with ready-made tokens for your users. See OAuth Flows Object for more details.
openIdConnectUrl
â- We do not support the
openIdConnect
security type.
- We do not support the
OAuth Flows Object
đ Specification Link
We currently do not support OAuth Flows anywhere so we currently ignore the
OAuth Flows Object
. We have plans to support this in the future.
implicit
â OAuth Flow Objectpassword
â OAuth Flow ObjectclientCredentials
â OAuth Flow ObjectauthorizationCode
â OAuth Flow Object
OAuth Flow Object
đ Specification Link
We do not support OAuth Flows anywhere currently so we ignore the
OAuth Flow Object
. We have plans to support this in the future.
authorizationUrl
tokenUrl
refreshUrl
scopes
Security Requirement Object
đ Specification Link
While we only support a subset of Security Scheme Objects, we can support all combinations of those objects. For example we can support multiple headers, one header or OAuth, one query parameter and one header and so on.
Specification Extensions
đ Specification Link
The OpenAPI specification allows for augmenting certain Objects with custom extensions and we support these, but only our extensions. If you have custom extensions in place for things like AWS API Gateways, they will be ignored.
For the full list of our extensions that we offer and support, see OpenAPI Extensions.
Updated 8 months ago