DEV Community

Cover image for What Changed in OpenAPI 3.2 vs 3.1 vs 3.0?
Wanda
Wanda

Posted on • Originally published at apidog.com

What Changed in OpenAPI 3.2 vs 3.1 vs 3.0?

#api #architecture #backend #documentation

TL;DR

OpenAPI 3.1 brings full JSON Schema compatibility, webhooks, and improved discriminator support. OpenAPI 3.2 adds QUERY method support, enhanced examples, and better security definitions. Modern PetstoreAPI implements OpenAPI 3.2, providing production-ready examples of all new features.

Introduction

When writing OpenAPI specs, you’ll encounter 3.0, 3.1, and 3.2 versions. Here’s how they differ, why you should consider upgrading, and what to expect from your tooling.

OpenAPI’s evolution from 3.0 to 3.2 introduces powerful features and improved accuracy for API specifications. However, tool support varies—so compatibility matters.

The legacy Swagger Petstore uses OpenAPI 2.0, while Modern PetstoreAPI demonstrates all OpenAPI 3.2 features with production-ready specs.

Try Apidog today

💡 Tip: If you’re building or testing REST APIs, Apidog supports OpenAPI 3.0, 3.1, and 3.2. You can import specs, validate schemas, and test implementations. Apidog helps you choose your version and migrate when needed.

This guide covers what changed in each OpenAPI version, how to choose or migrate, and how Modern PetstoreAPI demonstrates OpenAPI 3.2.

OpenAPI 3.0 Baseline

OpenAPI 3.0 (July 2017) was a major leap 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
Enter fullscreen mode Exit fullscreen mode

Swagger 2.0 only supported a single host.

2. Request Body Object

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

More explicit 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
Enter fullscreen mode Exit fullscreen mode

Improved organization over Swagger 2.0’s definitions.

4. Callbacks (Webhooks as Callbacks)

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

5. Links Between Operations

links:
  GetPetByPetId:
    operationId: getPetById
    parameters:
      petId: '$response.body#/id'
Enter fullscreen mode Exit fullscreen mode

Limitations

  1. JSON Schema Incompatibility: Used a subset of JSON Schema Draft 5, causing validation issues.
  2. No webhooks Object: Webhooks were modeled as callbacks, which was confusing.
  3. Limited Discriminator: Basic polymorphism only.
  4. No Null Type: Couldn’t directly specify type: null.

OpenAPI 3.1 Major Changes

OpenAPI 3.1 (Feb 2021) prioritizes JSON Schema alignment and clarity.

1. Full JSON Schema 2020-12 Compatibility

Schemas are now valid JSON Schema 2020-12.

Before (OpenAPI 3.0):

type: string
nullable: true  # OpenAPI-specific
Enter fullscreen mode Exit fullscreen mode

After (OpenAPI 3.1):

type: [string, "null"]  # JSON Schema standard
Enter fullscreen mode Exit fullscreen mode

Benefits:

  • Use standard JSON Schema validators
  • Schema sharing across tools
  • Full JSON Schema feature set

2. Webhooks Object

Before (3.0):

# Webhooks as callbacks
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # webhook definition
Enter fullscreen mode Exit fullscreen mode

After (3.1):

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

Now, API endpoints and webhooks are clearly separated.

3. Improved Discriminator

Better polymorphism with oneOf and mapping:

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

4. Info Object License Identifier 

info:
  license:
    name: MIT
    identifier: MIT  # SPDX identifier
Enter fullscreen mode Exit fullscreen mode

5. PathItem $ref

Reference entire path items:

paths:
  /pets:
    $ref: '#/components/pathItems/PetsCollection'
Enter fullscreen mode Exit fullscreen mode

Breaking Changes

  • nullable removed: Use type: [string, "null"].
  • exclusiveMinimum / exclusiveMaximum updated: Now boolean, not numeric.
  • example vs examples: Stricter validation.

OpenAPI 3.2 Latest Features

OpenAPI 3.2 (draft) modernizes API patterns.

1. QUERY Method Support

Support for 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
Enter fullscreen mode Exit fullscreen mode

Modern PetstoreAPI uses QUERY for advanced 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"
Enter fullscreen mode Exit fullscreen mode

3. Enhanced Security Definitions

Improved 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
Enter fullscreen mode Exit fullscreen mode

4. Improved Discriminator Mapping

Polymorphism with flexible mapping:

discriminator:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # Mix local and $ref
Enter fullscreen mode Exit fullscreen mode

5. Better Deprecation Support

Deprecate specific fields:

properties:
  oldField:
    type: string
    deprecated: true
    description: Use newField instead
  newField:
    type: string
Enter fullscreen mode Exit fullscreen mode

How Modern PetstoreAPI Uses OpenAPI 3.2

Modern PetstoreAPI demonstrates all OpenAPI 3.2 features in practice.

1. Full Specification

Full OpenAPI 3.2 spec:

https://petstoreapi.com/openapi.json
Enter fullscreen mode Exit fullscreen mode

2. QUERY Method for Complex Searches 

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

3. Webhooks 

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

4. Polymorphic Schemas 

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

5. Comprehensive Examples

Every endpoint includes multiple examples for different scenarios.

6. RFC 9457 Error Responses 

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

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"]
Enter fullscreen mode Exit fullscreen mode

2. Update exclusiveMinimum / exclusiveMaximum:

# Before
minimum: 0
exclusiveMinimum: true

# After
minimum: 0
exclusiveMinimum: 0
Enter fullscreen mode Exit fullscreen mode

3. Move webhooks:

# Before
paths:
  /subscribe:
    callbacks:
      # webhook

# After
webhooks:
  # webhook
Enter fullscreen mode Exit fullscreen mode

3.1 to 3.2

1. Add QUERY methods:

/pets/search:
  query:  # New in 3.2
    # complex search
Enter fullscreen mode Exit fullscreen mode

2. Enhance examples:

examples:
  example1:
    summary: Description
    value: {...}
Enter fullscreen mode Exit fullscreen mode

3. Update security definitions:

Add refreshUrl to OAuth flows.

Testing OpenAPI Specs with Apidog

Apidog supports all OpenAPI versions—import, validate, and test with practical workflows.

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
Enter fullscreen mode Exit fullscreen mode

Validate Spec

Apidog checks:

  • Schema validity
  • Reference integrity
  • Example correctness
  • Security definition completeness

Test API Implementation

Generate test cases from your OpenAPI spec:

  • Request validation
  • Response validation
  • Status code checks
  • Schema compliance

Version Comparison

Import multiple spec versions to compare:

  • Breaking changes
  • New endpoints
  • Schema changes
  • Deprecated fields

Conclusion

OpenAPI is evolving fast:

  • OpenAPI 3.0: Baseline with servers, request bodies, and callbacks
  • OpenAPI 3.1: Full JSON Schema compatibility, dedicated webhooks, improved polymorphism
  • OpenAPI 3.2: QUERY method, richer examples, improved security

Modern PetstoreAPI is a reference implementation for OpenAPI 3.2, showcasing all features in a real-world API.

Use Apidog to work with any OpenAPI version, validate specs, and test your API implementation.

FAQ

Should I upgrade to OpenAPI 3.1 or 3.2?

If your tooling supports it, upgrade. OpenAPI 3.1's JSON Schema compatibility is a major benefit. OpenAPI 3.2 adds modern API patterns like QUERY.

Will my OpenAPI 3.0 spec work with 3.1 tools?

Mostly, but update nullable and exclusiveMinimum/exclusiveMaximum.

Do code generators support OpenAPI 3.2?

Support is increasing. Check your code generator’s documentation—most support 3.1, fewer support 3.2.

Can I use OpenAPI 3.2 features in 3.1?

No. Use the version matching your needed features (e.g., QUERY method requires 3.2).

How do I validate my OpenAPI spec?

Use Apidog to import and validate your spec for schema and reference correctness.

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. In OpenAPI 3.0, they’re defined as callbacks. OpenAPI 3.1+ introduces a dedicated webhooks object.

Should I use JSON or YAML for OpenAPI specs?

Both are valid. YAML is more human-friendly; JSON works well for tooling. Modern PetstoreAPI offers both formats.

Top comments (0)