The terms 'Swagger' and 'OpenAPI' are often used interchangeably, leading to confusion. Swagger refers to SmartBear's open-source and commercial tooling ecosystem (Swagger UI, Swagger Editor), whereas OpenAPI refers to the open Linux Foundation specification standard.
1. Technical Feature Comparison Matrix
| Feature | Swagger 2.0 (Legacy) | OpenAPI 3.0 | OpenAPI 3.1 |
|---|---|---|---|
| Specification Root | swagger: '2.0' | openapi: '3.0.3' | openapi: '3.1.0' |
| Base URL Structure | host, basePath, schemes | servers array with templates | servers array with templates |
| JSON Schema Version | Custom schema subset | Draft 05 alignment | 100% JSON Schema 2020-12 |
| Request Payload | parameters (in: body) | requestBody object | requestBody object |
| Nullable Fields | x-nullable extension | nullable: true keyword | type: ['string', 'null'] |
| Webhooks Support | Not supported | Callbacks per operation | Native top-level webhooks object |
Swagger 2.0 vs OpenAPI 3.x Feature Matrix
2. Structural Code Migration Example
swagger2-vs-openapi3.yaml
# Legacy Swagger 2.0:
swagger: '2.0'
host: api.example.com
basePath: /v1
schemes:
- https
paths:
/users:
post:
parameters:
- in: body
name: body
schema:
$ref: '#/definitions/User'
# Modern OpenAPI 3.0:
openapi: 3.0.3
servers:
- url: https://api.example.com/v1
paths:
/users:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'Upgrade Your Swagger 2.0 Spec Automatically
Upload your legacy Swagger 2.0 specification into APIForge to inspect structural issues and convert it into OpenAPI 3.0/3.1 format.