Updated August 26, 2026
OpenAPI document structure reference
An OpenAPI document describes a REST API as a single JSON or YAML file. This sheet lists the root fields, the shape of a path operation, and the common HTTP methods so you can read or write a spec quickly.
Root fields
| Field | Required | Purpose |
|---|---|---|
openapi | Yes | Spec version string, e.g. 3.1.0 |
info | Yes | API title, version, and description |
servers | No | Base URLs the API is served from |
paths | Yes | Endpoints, each with methods and operations |
components | No | Reusable schemas, parameters, responses, security schemes |
security | No | Authentication applied to operations |
tags | No | Grouping labels for operations in docs |
Fields inside a path operation
| Field | Purpose |
|---|---|
summary | Short label for the operation |
operationId | Unique name used by code generators |
parameters | Path, query, header, and cookie inputs |
requestBody | Payload schema and media types |
responses | Status codes mapped to response schemas |
security | Auth required for this operation |
Common HTTP methods in paths
| Method | Typical use |
|---|---|
get | Read a resource; no request body |
post | Create a resource or run an action |
put | Replace a resource entirely |
patch | Update part of a resource |
delete | Remove a resource |
Swagger vs OpenAPISwagger 2.0 is the older format and uses a swagger: "2.0" field. OpenAPI 3.x replaces it with openapi: and moves reusable pieces under components. Most tools read both, but the field names differ.
Specs can be sensitiveAn OpenAPI document can expose internal endpoints, parameters, and auth schemes. Inspect it in a local, browser-only viewer so the spec is not uploaded to a third-party service.
References
Questions
Which OpenAPI fields are required?
openapi, info, and paths are required in OpenAPI 3.x. servers, components, security, and tags are optional but common.
Where do reusable schemas live?
Under components — for example components/schemas for data models and components/securitySchemes for auth. Operations reference them with $ref.