Anatomy of an OpenAPI Document
What you'll learn: You'll understand how an OpenAPI document is organized and what each major section describes about your API.
The Blueprint's Structure
An OpenAPI document is like a building blueprint for your API—it defines every entrance, room, and expected interaction. Just as architectural plans have standard sections (foundation, floor plans, elevations), OpenAPI documents follow a predictable structure that tools and humans can read.
Core Sections
info: Contains metadata about your API—title, version, description, contact information. Think of it as the title page of your API manual.
servers: Lists base URLs where your API lives (development, staging, production). This tells clients where to send requests.
paths: The heart of the document. Each path (like /users or /products/{id}) represents an API endpoint. Under each path, you define operations (GET, POST, PUT, DELETE) that specify what actions are possible.
components: A reusable library of definitions—schemas for request/response bodies, parameters, headers, and more. Instead of repeating the same "User" object structure everywhere, define it once here and reference it throughout.
Inside an Operation
Each operation under a path contains:
- parameters: Query strings, path variables, headers the endpoint accepts
- requestBody: The structure of data sent to the API (for POST/PUT)
- responses: What the API returns for each status code (200, 404, 500), including response schemas
This hierarchical structure—from paths to operations to parameters and responses—gives a complete picture of how to interact with every endpoint.
Key Takeaway: An OpenAPI document organizes API details into standardized sections (info, servers, paths, components), with paths defining endpoints and their operations, including parameters, request bodies, and response definitions.