OpenAPI Generator OpenAPI 3.1 — Migrating Specs from OpenAPI 3.0 to 3.1

In this tutorial, you will learn about OpenAPI Generator OpenAPI 3.1. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI Generator OpenAPI 3.1 Migration covers the changes between OpenAPI 3.0 and 3.1 that affect Code Generation, including JSON Schema 2020-12 alignment, nullable typing changes, Webhook support, and example enhancements.

What You'll Learn

• JSON Schema 2020-12 alignment
• Nullable changes (nullable -> type: [string, null])
• Webhook support in specs
• Example enhancements
• Generator compatibility considerations

Why It Matters

OpenAPI 3.1 introduces fundamental changes to schema authoring. The nullable keyword is replaced by JSON Schema 2020-12's type: [string, null] syntax. Nullable arrays and composed schemas behave differently. Upgrading requires updating both specs and generator configurations.

flowchart LR
    A["OpenAPI 3.0 Spec"] --> B["Schema changes"]
    A --> C["New features"]
    A --> D["Breaking changes"]

    B --> B1["nullable: true -> type: [string, null]"]
    B --> B2["allOf/oneOf now use JSON Schema 2020-12"]
    B --> B3["examples -> array of examples"]

    C --> C1["Webhooks support"]
    C --> C2["Path-level examples"]
    C --> C3["Improved description markdown"]

    D --> D1["Some generators don't support 3.1 yet"]
    D --> D2["Custom validators may need updates"]

What's Next

Update your {{< ilink "OpenAPI" "OpenAPI Generator Specification" }} for 3.1 compatibility, and test with {{< ilink "OpenAPI" "OpenAPI Generator Testing" }}.