How to Inspect an OpenAPI Specification
A 3.x OpenAPI file is a dense JSON or YAML contract. Learn where to look — info, servers, paths, components — and how a workbench turns the document into live requests and generated code.
In brief
- What is it?
- An OpenAPI specification (formerly Swagger) is a machine-readable description of an API: the server URLs (servers), every endpoint (paths), the request and response shapes (components.schemas) and the security schemes. Reading it tells you what a documented API can do before you write any code.
- Who is it for?
- Developers onboarding to a new API, evaluating one, or maintaining a contract, who need to find the key facts in a large YAML or JSON document without reading every line.
- How DataFormatter's tool is different
- The OpenAPI Viewer & Workbench parses a 3.x document into an interactive model — endpoint list, per-operation request and response schemas, code generation for multiple targets — so inspection replaces raw-file reading.
Before you integrate with an API, you read its contract. The single source of that truth is an OpenAPI document — a JSON or YAML file that declares every path, operation, schema and security scheme the server accepts. The file format is easy to read, but a real-world spec can be thousands of lines. Knowing where to look turns inspection from page-by-page reading into a five-minute walkthrough.
- OpenAPI 3.x
- The modern specification format: info, servers, paths, components and security are top-level objects describing the whole API surface.
- Path item
- An entry under paths keyed by URL template such as /users/{id}, listing the operations (get, post...) defined for that path.
- Reference ($ref)
- A pointer like #/components/schemas/Pet that names a schema once and reuses it everywhere, keeping the document DRY.
- Operation
- One request/response pairing: parameters, requestBody, responses and metadata for a single verb on a path.
The five places that answer everything
- info — title, version and description: what the API is and which contract you're looking at.
- servers — the base URLs (production, staging) that every path joins onto.
- paths — the endpoints themselves and the verbs each supports.
- components.schemas — the named shapes of the data: request bodies and response payloads.
- security — how you authenticate, whether per-schema or globally (API keys, bearer JWTs, OAuth).
Follow one request end to end
paths:
/orders/{id}:
get:
summary: Fetch an order
parameters:
- name: id
in: path
required: true
schema: { type: integer }
responses:
'200':
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }GET https://api.example.com/orders/123
→ 200, body shaped like the Order schemaStart with the operation you care about, follow its $refs into components.schemas, and you have the exact shape of the payload plus where it lives — which is everything needed to build or test the call.
Inspect with a workbench instead of a raw file
A specification viewer parses the document into the same structure — servers, endpoints, schemas — as an interactive model: select an endpoint, see its parameters and request/response schemas, send a live request against the chosen server, and generate code. Sanity problems like missing servers or malformed refs surface as validation issues, and a breakage review can compare two documents for breaking changes.
Frequently asked questions
Do I need to read the entire document?
No. Read info and servers once, then jump to the path you need and follow its refs. A workbench surfaces the same structure as clickable UI.
What's the difference between OpenAPI and Swagger?
Swagger is the original tooling name; OpenAPI is the specification itself (2.0 was still widely called Swagger 2.0). Modern contracts use OpenAPI 3.x.
How do I find the request body schema for a POST?
Its requestBody.content.application/json.schema, which usually $refs a components.schemas entry — dereference that to see the fields.
Can I test an endpoint straight from the document?
Yes — an OpenAPI workbench builds the request from the spec and lets you send it against the declared server, which is a fast way to confirm a documented call actually works.