Reading OpenAPI YAML
OpenAPI structure: paths, operations, parameters, $ref, response codes, and schema definitions
OpenAPI vocabulary
- paths — all endpoints; each path has operations (get/post/put/patch/delete)
- in: path/query/header/cookie — where the parameter is sent
- $ref: "#/components/schemas/X" — reusable schema reference
- required: [field] in schema — these fields are always present; others are optional
- enum — list of the only allowed values for a field
Question 0 of 5
An OpenAPI YAML file begins with: openapi: "3.0.3"
info:
title: Orders API
version: "1.2.0"
servers:
- url: https://api.example.com/v1
What do these top-level fields tell you?
- openapi — the specification version (2.0 = Swagger; 3.0.x, 3.1.x = OpenAPI)
- info.title — human-readable API name
- info.version — the API version (not the spec version)
- servers — base URL(s) for all endpoints; a path like
/ordersresolves tohttps://api.example.com/v1/orders - paths — the main section listing all endpoints
In an OpenAPI paths section:paths:
/orders/{orderId}:
get:
summary: Get order by ID
parameters:
- name: orderId
in: path
required: true
schema:
type: integer
What does in: path mean?
in:): - path — part of the URL:
/orders/42(always required: true) - query — URL query string:
/orders?status=pending - header — HTTP request header:
X-Request-Id: abc123 - cookie — HTTP cookie value
in: to know where the client should send the value; check required: true/false to know if it can be omitted; check schema.type for the expected data type (integer, string, boolean).An OpenAPI operation includes:requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateOrderRequest"
What does $ref mean here?
$ref: "#/components/schemas/X"— references a schema defined in thecomponents.schemassection of the same file$ref: "./other-file.yaml#/components/schemas/X"— references a schema in another file- All schemas, parameters, and responses can be defined once in
componentsand reused with$ref
$ref means "go look at the referenced definition to see the actual fields." Tools like Swagger UI resolve $refs automatically and show the expanded schema.An operation has this responses section:responses:
"200":
description: Order created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"422":
description: Validation error
What do the two status codes mean?
- 200 OK — success; body contains the response schema
- 201 Created — success for resource creation (often used instead of 200 for POST)
- 400 Bad Request — malformed request (invalid JSON, wrong content type)
- 401 Unauthorized — missing or invalid authentication
- 403 Forbidden — authenticated but lacks permission
- 404 Not Found — resource does not exist
- 422 Unprocessable Entity — request is well-formed but fails semantic validation (e.g., end date before start date)
- 429 Too Many Requests — rate limit exceeded
A components section contains:components:
schemas:
Order:
type: object
required: [id, status]
properties:
id:
type: integer
status:
type: string
enum: [pending, shipped, delivered]
note:
type: string
Which fields are guaranteed to be in every Order response?
- required: [field1, field2] — these fields must be present in the object
- properties — all possible fields, including optional ones
- enum — the only allowed values for a field; here status must be one of: pending, shipped, delivered
- type: object / array / string / integer / number / boolean — JSON primitive types
required are always present; fields in properties but not in required may be absent (treat them as optional in client code).