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 $ref to other attachments or URLs. Bundle them into one file first, for example with npx @redocly/cli bundle openapi.yaml -o bundled.yaml or swagger-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.

See What Apifolio does not do, and why.

View as Markdown