Supported OpenAPI features
Which OpenAPI 3.0, 3.1, 3.2 and Swagger 2.0 features Apifolio renders, from discriminators and nested tags to webhooks, server variables and OAuth flows.
Apifolio reads YAML and JSON files up to 25 MB, saved as UTF-8 or as UTF-16 (as some Windows tools save them).
| Feature | Support |
|---|---|
| Swagger 2.0 | Converted to OpenAPI 3 on the fly: body and form parameters, consumes/produces, securityDefinitions, collectionFormat, x-nullable, discriminators |
| OpenAPI 3.0 | Parameters, request bodies, responses, headers, links (which open the linked endpoint), callbacks, security, servers and server variables |
| OpenAPI 3.1 | JSON Schema 2020-12 types (type arrays, const, examples, prefixItems), $ref with sibling keywords, webhooks, summary in info |
| OpenAPI 3.2 | QUERY and other methods in additionalOperations, tag parent hierarchies nested to any depth, itemSchema for streams, in: querystring, dataValue/serializedValue examples, the OAuth device authorization flow |
$ref |
Internal references, including chains and recursion. References to other files and URLs are shown as such and never fetched |
| Composition | allOf merged into one model; oneOf/anyOf as switchable variants with one example each; discriminator with or without mapping, including inheritance (a base schema whose subtypes extend it with allOf) |
| Schema keywords | patternProperties, maps with named keys (x-additionalPropertiesName, propertyNames), not, if/then/else, dependentRequired, contentMediaType and contentEncoding as notes, read-only and write-only fields |
| Enums | Enum lists, oneOf lists of const values with titles and descriptions, x-enumDescriptions, x-enum-descriptions, x-enumNames, x-enum-varnames |
| Examples | example and named examples with their summaries and descriptions, schema examples, defaults and enums; generated from the schema when missing. Parameter examples become chips. externalValue examples are shown as a reference, never fetched |
| Security | API keys, HTTP basic and bearer, OAuth 2.0 flows with their URLs and scopes, OpenID Connect discovery URLs, mutual TLS, optional security and several alternatives per endpoint |
| Code samples | 17 languages, 8 tabs by default; x-codeSamples / x-code-samples shown first |
| Extensions | x-tagGroups, x-displayName, x-logo (from a data: image, or an image attached to the same page as the spec; a logo URL is shown as a link), x-codeSamples |
| Info | Description, termsOfService, externalDocs of the API, of sections and of endpoints |
| Data models only | A file with schemas and no endpoints (a data dictionary) shows its data models |
| Markdown | CommonMark and GitHub tables in descriptions, sanitised. Images are shown as links |
Not supported
- AsyncAPI documents.
- Specs split over several files, with
$refto other attachments or URLs. Bundle them into one file first, for example withnpx @redocly/cli bundle openapi.yaml -o bundled.yamlorswagger-cli bundle. When every path of the spec lives in other files, Apifolio lists them with this tip. - Live requests, and specs loaded from URLs or Git repositories.