Version Conversion

Working with Different OpenAPI Versions

Tigrister automatically handles Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 specs. Import any version and work seamlessly - conversions happen transparently.

Key Concepts
  • • Auto-Detection - Version is detected from swagger/openapi field
  • • Transparent Conversion - Swagger 2.0 specs convert to OpenAPI 3.0.3 internally
  • • Feature Parity - Most features map cleanly between versions
  • • Export Control - Choose output version during export

Version Compatibility Matrix

Feature availability varies by OpenAPI version. Tigrister supports all versions but some features only work in newer specs.

FeatureSwagger 2.0OpenAPI 3.0OpenAPI 3.1OpenAPI 3.2
Basic paths & operationsYesYesYesYes
JSON Schema (subset)YesYesYesYes
JSON Schema (full)--YesYes
Multiple servershost + schemesYesYesYes
Server variables-YesYesYes
Request body objectbody paramYesYesYes
Content negotiationproduces/consumescontent objectcontent objectcontent object
Callbacks-YesYesYes
Links-YesYesYes
Webhooks (top-level)--YesYes
PathItems in components--YesYes
$id, $anchor in schemas--YesYes

Swagger 2.0 → OpenAPI 3.x Conversion

Automatic

When you import a Swagger 2.0 spec, Tigrister automatically converts it to OpenAPI 3.0.3. This happens transparently - you can work with the spec normally.

Server URL Conversion

Swagger 2.0

host: api.example.com
basePath: /v1
schemes:
- https
- http

OpenAPI 3.x

servers:
- url: https://api.example.com/v1
description: HTTPS server
- url: http://api.example.com/v1
description: HTTP server
Request Body Conversion

Swagger 2.0 (body parameter)

parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/Pet'

OpenAPI 3.x (requestBody)

requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
Response Content Type

Swagger 2.0 (global produces)

produces:
- application/json
- application/xml
responses:
200:
schema:
$ref: '#/definitions/Pet'

OpenAPI 3.x (inline content)

responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
Component References

Swagger 2.0

definitions:
Pet: ...
# Reference:
$ref: '#/definitions/Pet'

OpenAPI 3.x

components:
schemas:
Pet: ...
# Reference:
$ref: '#/components/schemas/Pet'

OpenAPI 3.0 vs 3.1 Differences

OpenAPI 3.1 introduced significant changes, primarily around JSON Schema alignment. Tigrister handles both seamlessly.

Webhooks (3.1 Only)3.1+

Top-level webhooks define incoming HTTP requests your API receives. In 3.0, you must use callbacks attached to operations.

webhooks: # Only in 3.1
newOrder:
post:
summary: Receive new order notification
Nullable Handling

OpenAPI 3.0

type: string
nullable: true

OpenAPI 3.1 (JSON Schema)

type:
- string
- "null"
Example Keyword

OpenAPI 3.0

example: "John Doe"
# Only example (singular)

OpenAPI 3.1

examples:
- "John Doe"
- "Jane Smith"
# Plus example (singular)
New JSON Schema Keywords (3.1)
$id
$anchor
$dynamicRef
if/then/else
prefixItems
contentMediaType
contentEncoding
unevaluatedProperties

Version Detection

Tigrister automatically detects the spec version from the top-level field:

Swagger 2.0
swagger: "2.0"

Field must be exactly "2.0"

OpenAPI 3.0.x
openapi: "3.0.3"

Any 3.0.x version

OpenAPI 3.1.x
openapi: "3.1.0"

Any 3.1.x version

Detection Priority

If both swagger and openapi fields exist (invalid spec), the swagger field takes precedence.

OpenAPI 3.0 → 3.1 Upgrade

Automatic

Tigrister can also upgrade 3.0 specs to 3.1 for full JSON Schema support.

Schema Conversions

OpenAPI 3.0

nullable: true
type: string

OpenAPI 3.1

type:
- string
- "null"

OpenAPI 3.0

exclusiveMinimum: true
minimum: 0

OpenAPI 3.1

exclusiveMinimum: 0
Components Converted

All component types are converted during version upgrade:

schemasrequestBodiesresponsesparametersheaders

Conversion Warnings

When converting between versions, Tigrister returns detailed warnings about features that may be lost or modified.

ConversionWarnings Structure
interface ConversionWarnings {
hasWebhooks: boolean; // Webhooks will be lost (3.1 → 3.0)
hasJsonSchemaFeatures: boolean; // Advanced JSON Schema lost
unsupportedFeatures: string[]; // Detailed list
}
Example Warning
{
hasWebhooks: true,
unsupportedFeatures: [
"3 webhook(s) will be removed"
]
}
How to Use

Check warnings before finalizing export. If critical features would be lost, consider using a different target version or documenting the webhooks separately.

Export Version Selection

When exporting, you can choose the target version. Tigrister will adjust the spec structure as needed.

Export as 3.0.3

Maximum compatibility with existing tools.

  • - Webhooks removed
  • + Works everywhere
Export as 3.1.0

Full feature set including webhooks.

  • + Full JSON Schema
  • + Webhooks supported
Keep Original

Preserves the version from import.

  • + Minimal changes
  • + Round-trip fidelity

Conversion Considerations

Some features don't convert cleanly between versions:

Swagger 2.0 → 3.x
  • !File upload parameters become requestBody with multipart/form-data
  • !formData parameters move to requestBody
  • !Global produces/consumes become per-operation content types
  • !Security definitions → securitySchemes with different structure
3.1 → 3.0 (Downgrade)
  • !Webhooks are removed (no equivalent in 3.0)
  • !type: [string, null] → nullable: true conversion
  • !$id/$anchor references need manual adjustment
  • !Advanced JSON Schema keywords may be lost

Which Version Should I Use?

?

New Project, Modern Tools

Use OpenAPI 3.1 - full JSON Schema support and webhooks.

?

Maximum Tool Compatibility

Use OpenAPI 3.0.3 - widest tool support, stable specification.

?

Legacy System Integration

Import Swagger 2.0 - Tigrister converts it for you.

?

Code Generation

Check your generator's support - most work with 3.0.3.

Related Topics
→ Import→ Export→ Webhooks & Callbacks→ Schema Composition
Bi-Directional SyncExporting