What Changed in OpenAPI 3.2 vs 3.1 vs 3.0?

TL;DR

OpenAPI 3.1 added full JSON Schema compatibility, webhooks, and discriminator improvements. OpenAPI 3.2 added QUERY method support, improved examples, and better security definitions. Modern PetstoreAPI uses OpenAPI 3.2 to demonstrate all the latest features with production-ready examples.

Introduction

You’re writing an OpenAPI specification. You see references to OpenAPI 3.0, 3.1, and 3.2. What’s the difference? Should you upgrade? Will your tools support the new version?

OpenAPI has evolved significantly from 3.0 to 3.2. Each version adds features that make API specifications more powerful and accurate. But not all tools support the latest versions, creating a compatibility challenge.

The old Swagger Petstore uses OpenAPI 2.0 (Swagger specification). Modern PetstoreAPI uses OpenAPI 3.2, showcasing every new feature with production-ready examples.

💡

If you’re building or testing REST APIs, Apidog supports OpenAPI 3.0, 3.1, and 3.2. You can import specs, validate against the schema, and test your API implementation. Apidog helps you understand which version to use and how to migrate.

button

In this guide, you’ll learn what changed in each OpenAPI version, how to choose the right version, and how Modern PetstoreAPI demonstrates OpenAPI 3.2 features.

OpenAPI 3.0 Baseline

OpenAPI 3.0 (released July 2017) was a major upgrade from Swagger 2.0.

Key Features

1. Multiple servers

servers:
  - url: https://api.petstoreapi.com/v1
    description: Production
  - url: https://staging.petstoreapi.com/v1
    description: Staging

Swagger 2.0 only supported one host.

2. Request body object

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

Clearer than Swagger 2.0’s body parameter.

3. Components for reusability

components:
  schemas:
    Pet:
      type: object
  responses:
    NotFound:
      description: Resource not found
  parameters:
    PetId:
      name: petId
      in: path

Better organization than Swagger 2.0’s definitions.

4. Callbacks

Define asynchronous callbacks (webhooks):

callbacks:
  orderUpdate:
    '{$request.body#/callbackUrl}':
      post:
        requestBody:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderUpdate'

5. Links

Define relationships between operations:

links:
  GetPetByPetId:
    operationId: getPetById
    parameters:
      petId: '$response.body#/id'

Limitations

1. JSON Schema incompatibility

OpenAPI 3.0 used a subset of JSON Schema Draft 5, not full JSON Schema. This caused validation issues.

2. No webhooks object

Webhooks were defined as callbacks, which was confusing.

3. Limited discriminator

Polymorphism support was basic.

4. No null type

You couldn’t specify type: null directly.

OpenAPI 3.1 Major Changes

OpenAPI 3.1 (released February 2021) focused on JSON Schema alignment.

1. Full JSON Schema 2020-12 Compatibility

The biggest change: OpenAPI 3.1 schemas are valid JSON Schema 2020-12.

Before (OpenAPI 3.0):

type: string
nullable: true  # OpenAPI-specific

After (OpenAPI 3.1):

type: [string, "null"]  # Standard JSON Schema

Benefits:

Use any JSON Schema validator
Share schemas between OpenAPI and other tools
Access to full JSON Schema features

2. Webhooks Object

Before (OpenAPI 3.0):

# Webhooks defined as callbacks (confusing)
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # webhook definition

After (OpenAPI 3.1):

webhooks:
  orderUpdate:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'

Clearer separation between API endpoints and webhooks.

3. Improved Discriminator

Better polymorphism support:

oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
discriminator:
  propertyName: petType
  mapping:
    cat: '#/components/schemas/Cat'
    dog: '#/components/schemas/Dog'

4. Info Object License Identifier

info:
  license:
    name: MIT
    identifier: MIT  # SPDX identifier

5. PathItem $ref

Reference entire path items:

paths:
  /pets:
    $ref: '#/components/pathItems/PetsCollection'

Breaking Changes

1. nullable removed

Use type: [string, "null"] instead.

2. exclusiveMinimum/exclusiveMaximum changed

Now boolean, not numeric.

3. example vs examples

Stricter validation.

OpenAPI 3.2 Latest Features

OpenAPI 3.2 (released TBD, draft available) adds modern API patterns.

1. QUERY Method Support

HTTP QUERY method for complex searches:

paths:
  /pets/search:
    query:  # New method
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                sort:
                  type: array
      responses:
        '200':
          description: Search results

Modern PetstoreAPI uses QUERY for complex pet searches.

2. Improved Examples

Multiple examples with metadata:

examples:
  availableCat:
    summary: Available cat
    description: A cat available for adoption
    value:
      id: "019b4132-70aa-764f-b315-e2803d882a24"
      name: "Fluffy"
      species: "CAT"
      status: "AVAILABLE"
  adoptedDog:
    summary: Adopted dog
    value:
      id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
      name: "Buddy"
      species: "DOG"
      status: "ADOPTED"

3. Enhanced Security Definitions

Better OAuth 2.0 support:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://petstoreapi.com/oauth/authorize
          tokenUrl: https://petstoreapi.com/oauth/token
          refreshUrl: https://petstoreapi.com/oauth/refresh
          scopes:
            pets:read: Read pets
            pets:write: Create and update pets
            orders:read: Read orders

4. Improved Discriminator Mapping

More flexible polymorphism:

discriminator:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # Can mix local and $ref

5. Better Deprecation Support

Deprecate specific fields:

properties:
  oldField:
    type: string
    deprecated: true
    description: Use newField instead
  newField:
    type: string

How Modern PetstoreAPI Uses OpenAPI 3.2

Modern PetstoreAPI showcases every OpenAPI 3.2 feature.

1. Full Specification

The complete OpenAPI 3.2 spec is available at:

https://petstoreapi.com/openapi.json

2. QUERY Method for Complex Searches

/pets/search:
  query:
    summary: Search pets with complex criteria
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PetSearchQuery'

3. Webhooks

webhooks:
  petStatusChanged:
    post:
      summary: Pet status changed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetStatusWebhook'

4. Polymorphic Schemas

Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Bird'
  discriminator:
    propertyName: species

5. Comprehensive Examples

Every endpoint includes multiple examples showing different scenarios.

6. RFC 9457 Error Responses

responses:
  '400':
    description: Bad Request
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'

See the complete OpenAPI spec for all features.

Migration Guide

3.0 to 3.1

1. Replace nullable:

# Before
type: string
nullable: true

# After
type: [string, "null"]

2. Update exclusiveMinimum/exclusiveMaximum:

# Before
minimum: 0
exclusiveMinimum: true

# After
minimum: 0
exclusiveMinimum: 0

3. Move webhooks:

# Before
paths:
  /subscribe:
    callbacks:
      # webhook

# After
webhooks:
  # webhook

3.1 to 3.2

1. Add QUERY methods where appropriate:

/pets/search:
  query:  # New in 3.2
    # complex search

2. Enhance examples:

examples:
  example1:
    summary: Description
    value: {...}

3. Update security definitions:

Add refreshUrl to OAuth flows.

Testing OpenAPI Specs with Apidog

Apidog supports all OpenAPI versions.

Import OpenAPI Spec

1. Open Apidog
2. Click "Import"
3. Select "OpenAPI 3.x"
4. Paste URL or upload file
5. Apidog validates and imports

Validate Spec

Apidog checks:

Schema validity
Reference integrity
Example correctness
Security definition completeness

Test API Implementation

Generate test cases from the spec:

Request validation
Response validation
Status code checks
Schema compliance

Version Comparison

Import multiple versions and compare:

Breaking changes
New endpoints
Schema changes
Deprecated fields

Conclusion

OpenAPI has evolved significantly:

OpenAPI 3.0: Foundation with servers, request bodies, callbacks

OpenAPI 3.1: JSON Schema compatibility, webhooks object, better polymorphism

OpenAPI 3.2: QUERY method, enhanced examples, improved security

Modern PetstoreAPI uses OpenAPI 3.2 to demonstrate all features with production-ready examples. It’s the reference implementation for modern API design.

Use Apidog to work with any OpenAPI version, validate specs, and test implementations.

FAQ

Should I upgrade to OpenAPI 3.1 or 3.2?

If your tools support it, yes. OpenAPI 3.1’s JSON Schema compatibility is valuable. OpenAPI 3.2 adds modern patterns like QUERY method.

Will my OpenAPI 3.0 spec work with 3.1 tools?

Mostly, but nullable and exclusiveMinimum/exclusiveMaximum need updates.

Do code generators support OpenAPI 3.2?

Support is growing. Check your generator’s documentation. Many support 3.1, fewer support 3.2.

Can I use OpenAPI 3.2 features in 3.1?

No. Use the version that matches your features. If you need QUERY method, use 3.2.

How do I validate my OpenAPI spec?

Use Apidog to import and validate your spec. It checks schema validity and reference integrity.

Where can I see a complete OpenAPI 3.2 example?

Modern PetstoreAPI provides a complete, production-ready OpenAPI 3.2 specification.

What’s the difference between webhooks and callbacks?

Webhooks are server-to-client HTTP requests. Callbacks are defined in OpenAPI 3.0 as part of operations. OpenAPI 3.1+ has a dedicated webhooks object.

Should I use JSON or YAML for OpenAPI specs?

Both work. YAML is more readable for humans. JSON is easier for tools. Modern PetstoreAPI provides both formats.