How do you convert a Swagger 2.0 document to OpenAPI 3.0?

Converting between the two versions is largely a mechanical, structural transformation, and dedicated conversion tools handle the bulk of it automatically, though the result usually still benefits from a manual review pass afterward.

# Using the swagger2openapi CLI tool
npx swagger2openapi swagger.yaml -o openapi.yaml

• definitions → components/schemas: every schema is relocated and every internal $ref path is rewritten to match.
• host/basePath/schemes → servers: combined into one or more full server URLs.
• body-type parameters → requestBody: the awkward in: body parameter becomes a proper requestBody object.
• produces/consumes → content: media types move from operation-level arrays into per-response/request content maps.
• securityDefinitions → components/securitySchemes: renamed and relocated, with matching structural adjustments.

Automated conversion tools handle these structural mappings reliably, but they generally can't infer intent that wasn't explicit in the original document — for example, deciding whether a response should now describe multiple content types, or cleaning up any pre-existing inconsistencies in the Swagger 2.0 source — so a manual review against the newly generated OpenAPI 3.0 document, particularly re-rendering it in Swagger UI to visually spot-check the result, is a worthwhile final step before treating the migration as complete.