Backend Study Lab

API Design

OpenAPI Explained for Backend Developers

Learn how OpenAPI describes REST APIs, including paths, operations, schemas, examples, auth, versioning, code generation, and contract review.

By CloveCode Studio Jun 30, 2026 Updated Jul 1, 2026 4 min read

OpenAPI is a machine-readable description of an HTTP API. Backend teams use it to document endpoints, validate contracts, generate clients, review changes, and keep examples close to real API behavior.

Quick answer

OpenAPI describes an API contract: paths, methods, parameters, request bodies, responses, schemas, authentication, examples, and metadata.

It is most useful when treated as part of the backend contract, not as a static document written after the code is done. A good OpenAPI file helps humans understand the API and helps tools generate docs, SDKs, mocks, and tests.

What OpenAPI describes

An OpenAPI document usually answers these questions:

  • Which paths exist?
  • Which HTTP methods are allowed?
  • Which query parameters, path parameters, and headers are accepted?
  • What request body shape is valid?
  • What response body shape can clients expect?
  • Which status codes can be returned?
  • How does authentication work?
  • What examples should client developers copy?

A tiny path might look like this:

paths:
  /orders/{orderId}:
    get:
      summary: Get an order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found

The real value comes from filling in response schemas, error cases, security requirements, and examples.

Paths and operations

Each path contains operations such as get, post, put, patch, and delete.

Good operation descriptions explain the client-visible behavior, not the internal service implementation. For example, “Create an order” is more useful than “Calls OrderService.create”.

Each operation should define:

  • A stable operationId if code generation or SDKs use it.
  • Required parameters.
  • Request body schema when needed.
  • Success responses.
  • Common error responses.
  • Security requirements.
  • Examples for realistic client usage.

If you are deciding between endpoint styles, read REST vs RPC. If you are defining update operations, read PUT vs PATCH in REST APIs.

Schemas and examples

OpenAPI schemas describe JSON object shapes, primitive types, arrays, required fields, enum values, and nested objects.

components:
  schemas:
    Order:
      type: object
      required: [id, status, totalCents]
      properties:
        id:
          type: string
          example: ord_123
        status:
          type: string
          enum: [pending, paid, cancelled]
        totalCents:
          type: integer
          example: 4200

Schemas are useful, but examples are equally important. A technically valid schema can still leave client developers guessing about realistic IDs, timestamps, pagination metadata, nested objects, and error shapes.

Use the JSON Schema Generator and JSON to TypeScript Types Generator to draft and inspect API payload shapes locally.

Authentication and security schemes

OpenAPI can document security schemes such as bearer tokens, API keys, OAuth flows, and basic authentication.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

This does not secure the API by itself. It only documents what clients must send and what tools can display.

For practical credential tradeoffs, read API Key vs OAuth Token and API Key Design Best Practices.

Status codes and error responses

OpenAPI should include more than happy paths.

For a public endpoint, document common failures:

responses:
  "400":
    description: Invalid request body
  "401":
    description: Authentication required
  "403":
    description: Caller is not allowed
  "404":
    description: Resource not found
  "429":
    description: Rate limit exceeded

If every endpoint returns a different error shape, clients will struggle even if the OpenAPI document is technically complete. Read REST API Error Handling Best Practices before defining shared error schemas.

OpenAPI in the development workflow

Teams usually use one of two workflows.

Design-first means the API contract is reviewed before implementation. This works well for public APIs, SDKs, and cross-team integrations because clients can review the contract early.

Code-first means the contract is generated from backend annotations, route definitions, or types. This can reduce duplication, but generated specs still need review. Generated OpenAPI can easily miss examples, business meaning, deprecation notes, and real error behavior.

Either workflow should include contract review in pull requests.

Versioning and compatibility

OpenAPI makes breaking changes easier to spot, but it does not decide versioning policy for you.

Breaking changes include removing fields, changing field types, removing endpoints, changing required parameters, or changing error response shapes that clients depend on.

Use OpenAPI diff tooling or contract tests when the API is public or shared across teams. Read API Versioning Explained before changing a published contract.

Common mistakes

The first mistake is documenting only 200 OK. Real clients need to know how validation, auth, conflicts, rate limits, and server failures are represented.

The second mistake is letting examples drift away from production behavior. Examples should use realistic field names, IDs, timestamps, pagination metadata, and error bodies.

The third mistake is relying on generated specs without human review. Generated schemas can describe types while still failing to explain meaning.

The fourth mistake is treating OpenAPI as the only source of truth for webhooks, events, SDK behavior, and migration notes. Those may need companion docs.

Read JSON Schema vs OpenAPI Schema for schema boundaries, REST API Design Checklist before publishing endpoints, Spring Boot REST Controller Explained for a framework-level endpoint example, API Versioning Explained for compatibility planning, and REST API Status Codes Explained for response contracts. Use JSONPath Tester and JSON Pointer Resolver while inspecting nested examples, schemas, and error paths. For the full sequence, browse the API Design Learning Path and the Topics map.

Keep reading