What is the difference between OpenAPI 2.0 (Swagger) and 3.0?

OpenAPI 3.0 supports multiple server URLs, improved media type handling, requestBody instead of body parameters, and reusable component schemas. It is the current standard.

What does $ref do in OpenAPI?

$ref is a JSON Reference that points to a reusable schema component, avoiding duplication. It can reference schemas within the same file or in external files.

Can I generate client code from an OpenAPI spec?

Yes. Tools like openapi-generator and swagger-codegen can generate type-safe client libraries in dozens of languages directly from a valid OpenAPI specification.

Validate an OpenAPI Specification

OpenAPI specifications document REST API contracts and are consumed by code generators, API gateways, and documentation tools. YAML formatting errors cause these tools to fail silently or with confusing messages. This example shows a minimal OpenAPI 3.0 spec for a users endpoint. Validate the YAML syntax first, then use a dedicated OpenAPI linter for schema-level validation.

Example

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string }

[ open in YAML Validator → ]

FAQ

What is the difference between OpenAPI 2.0 (Swagger) and 3.0?: OpenAPI 3.0 supports multiple server URLs, improved media type handling, requestBody instead of body parameters, and reusable component schemas. It is the current standard.
What does $ref do in OpenAPI?: $ref is a JSON Reference that points to a reusable schema component, avoiding duplication. It can reference schemas within the same file or in external files.
Can I generate client code from an OpenAPI spec?: Yes. Tools like openapi-generator and swagger-codegen can generate type-safe client libraries in dozens of languages directly from a valid OpenAPI specification.

Related Examples

Validate a GitHub Actions Workflow

GitHub Actions workflows are YAML files where formatting errors prevent pipeline...

Format a REST API Response

REST APIs return compact JSON that is hard to read at a glance. Paste this examp...

Format a GraphQL Response

GraphQL responses always follow a predictable envelope with a data field and an ...