Version Conversion
Working with Different OpenAPI Versions
Atrahasis handles Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 specs with automatic conversion between them. OpenAPI 3.2.0 is supported for reading and editing, but there is no automatic conversion to or from 3.2 yet.
Key Concepts
- • Auto-Detection - Version is detected from the swagger/openapi field
- • Swagger 2.0 → OpenAPI 3.0.3 - Transparent upgrade on import
- • OpenAPI 3.0 ↔ 3.1 - Bi-directional conversion (nullable, exclusiveMinimum, etc.)
- • OpenAPI 3.2 - Read and edit only; no conversion path
- • Export Control - Choose output version during export
Version Compatibility Matrix
Feature availability varies by OpenAPI version. Atrahasis supports all versions but some features only work in newer specs.
| Feature | Swagger 2.0 | OpenAPI 3.0 | OpenAPI 3.1 | OpenAPI 3.2 |
|---|---|---|---|---|
| Basic paths & operations | Yes | Yes | Yes | Yes |
| JSON Schema (subset) | Yes | Yes | Yes | Yes |
| JSON Schema (full) | - | - | Yes | Yes |
| Multiple servers | host + schemes | Yes | Yes | Yes |
| Server variables | - | Yes | Yes | Yes |
| Request body object | body param | Yes | Yes | Yes |
| Content negotiation | produces/consumes | content object | content object | content object |
| Callbacks | - | Yes | Yes | Yes |
| Links | - | Yes | Yes | Yes |
| Webhooks (top-level) | - | - | Yes | Yes |
| PathItems in components | - | - | Yes | Yes |
| $id, $anchor in schemas | - | - | Yes | Yes |
Swagger 2.0 → OpenAPI 3.x Conversion
AutomaticWhen you import a Swagger 2.0 spec, Atrahasis automatically converts it to OpenAPI 3.0.3. This happens transparently - you can work with the spec normally.
Server URL Conversion
Swagger 2.0
OpenAPI 3.x
Request Body Conversion
Swagger 2.0 (body parameter)
OpenAPI 3.x (requestBody)
Response Content Type
Swagger 2.0 (global produces)
OpenAPI 3.x (inline content)
Component References
Swagger 2.0
OpenAPI 3.x
OpenAPI 3.0 vs 3.1 Differences
OpenAPI 3.1 introduced significant changes, primarily around JSON Schema alignment. Atrahasis 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.
Nullable Handling
OpenAPI 3.0
OpenAPI 3.1 (JSON Schema)
Example Keyword
OpenAPI 3.0
OpenAPI 3.1
New JSON Schema Keywords (3.1)
Version Detection
Atrahasis automatically detects the spec version from the top-level field:
Swagger 2.0
Field must be exactly "2.0"
OpenAPI 3.0.x
Any 3.0.x version
OpenAPI 3.1.x
Any 3.1.x version
OpenAPI 3.2.0
Read/edit only — no conversion
Detection Priority
If both swagger and openapi fields exist (invalid spec), the swagger field takes precedence.
OpenAPI 3.0 → 3.1 Upgrade
AutomaticAtrahasis can also upgrade 3.0 specs to 3.1 for full JSON Schema support.
Schema Conversions
OpenAPI 3.0
OpenAPI 3.1
OpenAPI 3.0
OpenAPI 3.1
Components Converted
All component types are converted during version upgrade:
Conversion Warnings
When converting between versions, Atrahasis returns detailed warnings about features that may be lost or modified.
ConversionWarnings Structure
Example Warning
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. Atrahasis 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 - Atrahasis converts it for you.
Code Generation
Check your generator's support - most work with 3.0.3.