OpenAPI Vocabulary

Paths = endpoints and operations; Components = reusable definitions referenced with $ref. OpenAPI 3.x structure:

• paths: /users/{id} → GET, POST, PUT, DELETE operations with their parameters, request bodies, and responses
• components:
  • schemas: reusable data models (User, Error, PaginatedResponse)
  • parameters: reusable query params, headers (X-API-Version, page, limit)
  • responses: reusable response bodies (404NotFound, 401Unauthorized)
  • securitySchemes: Bearer token, API key definitions

Using components with $ref eliminates duplication: define the User schema once, reference it from POST /users response and GET /users/{id} response instead of copying.

Unique identifier for each operation — used by SDK generators to name functions. operationId conventions:

• ✅ camelCase: getUser, createUser, deleteUserById
• ✅ Verb + noun: listPayments, updateSubscription, cancelOrder
• ❌ Avoid: spaces, special characters, duplicate IDs in the same spec

Why operationId matters:

• TypeScript SDK generator creates: client.getUser(id) — readable, matches intent
• Without operationId: generator may create: client.usersIdGet(id) — mechanical, harder to use
• API documentation tools use operationId as the anchor for deep-linking to specific operations

requestBody: required: true + content: application/json: schema:. OpenAPI 2.x vs. 3.x change:

• ❌ OpenAPI 2.x: parameters: - in: body — the old way
• ✅ OpenAPI 3.x: requestBody: required: true, content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest'

requestBody example:

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateUserRequest'
      example:
        email: user@example.com
        name: Jane Smith

The example field is critical for documentation quality — it shows developers what to send without reading the full schema.

nullable: true = OpenAPI 3.0 extension; type: [string, null] = JSON Schema standard (OpenAPI 3.1). Version differences:

• OpenAPI 3.0: nullable: true + type: string — proprietary extension, not in JSON Schema
• OpenAPI 3.1: type: [string, null] or oneOf: [{type: string}, {type: null}] — standard JSON Schema

Also important — "nullable" vs. "optional":

• Optional field: field may be absent from the object — not listed in required:
• Nullable field: field is present but its value is null — type: [string, null]
• Required + nullable: field must be present, but can be null — in required AND type: [string, null]

example = single value; examples = multiple named examples with descriptions. When to use each:

• example: simple property-level example — email: { type: string, example: "user@example.com" }
• examples: operation-level, multiple scenarios — examples: successCase: { summary: "...", value: {...} }, errorCase: { summary: "...", value: {...} }

examples adds value when:

• An endpoint behaves differently for different inputs (filter active vs. inactive users)
• You want to show error response bodies alongside success responses
• Edge cases need illustration (empty results, pagination last page)

Documentation tools like Swagger UI and Redoc render multiple examples as a dropdown, letting developers explore scenarios without reading the full spec.