OpenAPI 3.1 Essentials

OpenAPI 3.1 is fully aligned with JSON Schema 2020-12 (nullable via type: [string, "null"], examples, const), and supports top-level webhooks. A good spec has: info with contact and version, servers, operations with operationId, summary and description, parameters with schemas and examples, request bodies, every response (including errors) with schemas, securitySchemes and per-operation security, and reusable components.

3.0 vs 3.1

openapi: 3.1.0
info: { title: Orders API, version: 2026.10.0, contact: { email: [email protected] } }
servers: [{ url: https://api.example.com/v1 }]
security: [{ oauth2: [orders:read] }]
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get an order
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string, pattern: "^ord_[0-9A-Z]{26}$" } }
      responses:
        "200":
          headers: { ETag: { schema: { type: string } } }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
              examples: { paid: { $ref: "#/components/examples/PaidOrder" } }
        "404": { $ref: "#/components/responses/NotFound" }
webhooks:
  orderPaid:
    post:
      requestBody: { content: { application/json: { schema: { $ref: "#/components/schemas/OrderPaidEvent" } } } }
      responses: { "200": { description: Acknowledged } }
components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id: { type: string }
        status: { type: string, enum: [pending, paid, shipped, cancelled] }
        total: { $ref: "#/components/schemas/Money" }
        note: { type: [string, "null"] }
  securitySchemes:
    oauth2:
      type: oauth2
      flows: { clientCredentials: { tokenUrl: https://auth.example.com/token, scopes: { orders:read: Read orders } } }

Common pitfalls

• Missing error responses.
• No examples (docs and mocks become useless).
• operationIds missing or unstable (breaks SDK method names).

Key points

• 3.1 = JSON Schema 2020-12 + webhooks
• Document every response and security
• Stable operationIds and examples

Further reading: OpenAPI Specification 3.1