definitions: → components.schemas:.
How-to
Convert Swagger 2.0 to OpenAPI 3.x.
Swagger 2.0 specs still work, but every modern tool reads OpenAPI 3.x more cleanly. This page walks the conversion mechanically, with the structural changes that matter and how to verify nothing breaks for clients.
Completely free for 30 days. No credit card required.
01Details
The structural changes
Body parameters → requestBody:.
host: + basePath: + schemes: → servers:.
securityDefinitions: → components.securitySchemes:.
oneOf / anyOf / allOf are first-class (in 3.x).
02Details
Tools that automate most of it
Bloom's report runs the conversion as part of a migration scan and flags what needs human review.
swagger-cli ships a converter (swagger2openapi).
Spectral's preset for OpenAPI 3 will lint the converted output.
03Details
What human review catches
Custom x-* extensions whose semantics may differ between tools.
example: and examples: placement (3.x is stricter).
Operations that used consumes: / produces: (now belong on each request/response media type).
04Details
How to verify the conversion is safe
Validate the 3.x output with Spectral, Stoplight, or openapi-cli.
Generate clients from the 3.x spec and diff them against clients generated from the original 2.0 spec.
Bloom's compatibility report does this diff automatically; the goal is zero missing methods and zero type narrowings.
05Details
Should you go to 3.0 or straight to 3.1?
3.1 is recommended unless you have a hard dependency on a tool that only reads 3.0.
The JSON Schema 2020-12 alignment in 3.1 makes SDK and validator output noticeably cleaner.