Swagger 2 vs OpenAPI 3

OpenAPI 3 is not a header-only rename. It reorganizes reusable definitions, server URLs, request bodies, media types, security schemes, and response content.

Version marker and server URLs

A Swagger 2 document begins with swagger: "2.0". OpenAPI 3 uses an openapi version such as 3.0.3 or a later supported 3.x release. Swagger 2 builds an endpoint from schemes, host, and basePath. OpenAPI 3 replaces those fields with a servers array containing complete URL templates.

Request bodies and media types

Swagger 2 represents body input as a parameter with in: body, while form fields use other parameter forms. OpenAPI 3 introduces requestBody and places representations under content. Each media type can have its own schema and examples.

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/User'

Likewise, response schemas move under each response’s content map. Global consumes and produces lists are replaced by explicit media types where the request or response is declared.

Definitions become components

Reusable Swagger 2 schemas under definitions move to components.schemas. Parameters, responses, headers, examples, links, callbacks, and security schemes also have named component areas. Every moved $ref must be updated; a valid old pointer can silently reference nothing after a mechanical file edit.

Security and schema differences

Security definitions move to components.securitySchemes. OpenAPI 3 provides clearer HTTP bearer and OpenID Connect descriptions and changes OAuth flow structure. Schema behavior also evolves across OpenAPI 3 releases, so nullable values and JSON Schema keywords deserve explicit validation against the target version.

A safe migration sequence

1. Freeze a tested Swagger 2 baseline and representative requests.
2. Convert structure without intentionally changing API behavior.
3. Validate the resulting spec with the OpenAPI Validator and your production toolchain.
4. Compare generated documentation, clients, and mock responses.
5. Review the old and new contract for accidental breaking changes.

Keep representation migration separate from endpoint redesign. A smaller diff makes missing parameters, changed required flags, and broken references easier to spot.

Frequently Asked Questions

Related Tools and Guides