Skip to content

Supported specifications

This page describes which input specification versions the CLI, Gradle plugin, and core engine accept. All supported inputs are parsed into io.swagger.v3.oas.models.OpenAPI before generation, so providers, rules, and generators use the same model shape.

Version support

Input version Status Notes
OpenAPI 3.0.x Supported Parsed directly by swagger-parser-v3 and used as the generator's native model.
OpenAPI 3.1.x Supported best-effort Parsed by the configured swagger-parser-v3 version. Generation covers the schema features supported by the core providers and rules.
Swagger 2.0 Supported through normalization Parsed with the Swagger 2.0 converter, normalized to an OpenAPI 3 model, then generated through the same pipeline as OpenAPI 3 specs.
Swagger 1.x Unsupported Files with swagger values other than "2.0" fail before generation with an unsupported-version error.

Declare the spec version the parser detects

The version is detected from the spec's top-level version field. Any of these headers is accepted as-is — no flag or setting selects the version:

# OpenAPI 3.0.x
openapi: 3.0.3

# OpenAPI 3.1.x
openapi: 3.1.0

# Swagger 2.0 (normalized to an OpenAPI 3 model before generation)
swagger: "2.0"

Swagger 2.0 normalization

Swagger 2.0 support is an input compatibility layer. The public CLI, Gradle plugin, and core generator APIs still take one specFile and still operate on OpenAPI 3 model classes internally.

The adapter covers:

Swagger 2.0 input Normalized OpenAPI 3 shape
host, basePath, schemes servers
paths operations paths operations
Path-level parameters Merged into each operation's parameter list unless an operation overrides the same in/name pair
Query, path, and header parameters OpenAPI 3 parameter models, including deterministic style/explode values for converted collection formats
body parameters requestBody.content
formData parameters application/x-www-form-urlencoded or multipart/form-data request bodies
consumes / produces Request and response content media types, with operation-level values taking precedence over global values
definitions components.schemas with OpenAPI 3 $ref targets
Reusable parameters, responses, examples, and security definitions components maps
securityDefinitions for apiKey, basic, and oauth2 OpenAPI 3 security schemes
x-* vendor extensions Preserved on the normalized model; generation ignores them unless a provider or custom rule uses them

Generation limits

  • Generation targets operations under paths. OpenAPI 3 webhooks are parsed but not generated into suites.
  • Swagger 2.0 multipart/form-data request bodies are parsed and preserved, but multipart media types are not generated by the built-in request-body providers. They are logged as unsupported media types.
  • Swagger 2.0 file upload schemas are not converted into upload payload values by the built-in generators.
  • Unsupported request body media types are skipped. Built-in request-body generation supports JSON, text/json, JWT, XML, YAML, application/x-www-form-urlencoded, and +json / +jwt / +xml suffixes.
  • Swagger 2.0 parser settings use the same SnakeYAML parser settings as OpenAPI 3 input.
  • Swagger 2.0 specs are processed as single documents: $refs pointing at other files or URLs are not resolved on the conversion path and their constraints are dropped from generated suites. Bundle multi-file Swagger 2.0 specs into one document first. OpenAPI 3 input resolves external $refs normally.