OpenAPI Viewer

Reading a spec without waiting for the docs to render

An OpenAPI document is the contract for an HTTP API: every path, every method, what goes in, what comes back. It is also, in practice, four thousand lines of YAML that somebody hands you with "the endpoint you want is in there somewhere".

The usual answer is to load it into Swagger UI, which is excellent for exploring one endpoint in depth and poor at the question you normally have first — what endpoints exist at all? That question is answered by a table. Paste the spec, get one row per operation, and the shape of the API is visible in a glance instead of a scroll.

Both major versions work. OpenAPI 3.x is the current one; Swagger 2.0 is still very much alive in older estates and the two differ enough to matter — 3.x moved the request body out of the parameter list into its own requestBody object, so a Swagger 2 spec has a body parameter where a 3.x spec has nothing in that column. Both are read here and the difference is not hidden from you.

Parsing happens in your browser, so an internal spec you should not be uploading anywhere is safe to paste. YAML is handled by the same parser the rest of this site uses, which means the usual YAML traps apply to your spec too — an unquoted version number in a spec is a real and irritating source of confusion.

How to use it

1. Paste the spec – JSON or YAML, either version. Most teams keep it as openapi.yaml in the repository; many services also serve it at /openapi.json or /swagger.json.
2. Scan the table – One row per method-and-path pair, in the order the spec declares them, with the summary the authors wrote.
3. Filter to the part you care about – Type a path fragment, a method or a word from a summary. On a large spec this is how you find the four endpoints that concern you.
4. Note the response codes – The codes column is often the fastest way to spot an endpoint that only documents 200 — which usually means nobody has thought about its failure modes.

The tags an operation carries are how Swagger UI groups endpoints into sections, and they are worth checking when a spec feels disorganised. An operation with no tag ends up in a "default" bucket that most rendered documentation puts last, so a genuinely important endpoint can end up looking like an afterthought purely because someone forgot one line.

A spec, and the table it becomes

Part of a SIM provisioning API. In YAML it takes about forty lines to describe three operations, and the nesting means the paths and the methods are on different indentation levels — which is exactly why the flat table is easier to read.

paths:
  /subscribers:
    get:
      summary: List subscribers
      parameters:
        - name: status
          in: query
      responses:
        "200": …
        "400": …
  /subscribers/{msisdn}:
    # applies to every operation below
    parameters:
      - name: msisdn
        in: path
        required: true
    get:
      summary: Fetch one subscriber

GET  /subscribers
     List subscribers
     status (query)
     200 400

POST /subscribers
     Provision a new SIM
     body* (requestBody)
     201 409 422

GET  /subscribers/{msisdn}
     Fetch one subscriber
     msisdn* (path)  ← inherited
     200 404

When you would open this

Someone sends you a spec and asks you to integrate

The first thing you need is an inventory: how many endpoints, what do they cover, is the thing you need actually in there. That is a table question, and it takes seconds rather than the several minutes of scrolling that rendered documentation requires.

Reviewing an API change

A diff of an OpenAPI file is nearly unreadable — a moved block looks like a rewrite. Viewing the before and the after as tables makes an added endpoint or a changed method obvious. For the fine detail, JSON Diff on the two specs picks up the rest.

Lifting a schema out to test against

Once you know which operation you care about, its request and response schemas are ordinary JSON Schema documents sitting inside the spec. Copy one into the schema validator and you can check a real payload against the published contract without touching the service.

Auditing what an API actually exposes

A flat list of every path and method is the version of a spec that is useful in a security review. Endpoints nobody remembers writing tend to be visible in a table and invisible in a nested document.

What it reads

• OpenAPI 3.0 and 3.1, and Swagger 2.0 — the version is detected from the document rather than guessed.
• JSON or YAML input. Most specs in a repository are YAML; most specs served over HTTP are JSON.
• Path-level parameters merged into each operation, which is where a shared {id} is usually declared and where a naive reader misses it.
• The requestBody of an OpenAPI 3 operation, which is not a parameter but is very much an input.
• Response codes per operation, so a missing error case is visible without opening anything.
• Deprecated operations marked, because they are easy to integrate against by accident.
• A filter across method, path, summary and tags for the specs that run to hundreds of endpoints.

Questions worth answering

Does it resolve $ref to other files?

References within the same document resolve, including the #/components/schemas/… form that nearly every spec uses. External file references do not, because the page makes no network requests and has no filesystem to read from. If your spec is split across files, bundle it first — Redocly and swagger-cli both do this in one command, and a bundled spec is what you want to publish anyway.

Why does my Swagger 2 spec show nothing in the request body column?

It will not — in Swagger 2.0 the request body is a parameter with "in": "body", so it appears in the parameters column instead. OpenAPI 3 pulled it out into a separate requestBody object. This is the single most common source of confusion when converting between the two versions, and it is why a 3.x converter that treats the body as a parameter produces a spec that validates and means the wrong thing.

Is this a replacement for Swagger UI?

No, and it is not trying to be. Swagger UI renders full documentation and lets you send requests; it is the right tool once you know which endpoint you want. This is the step before that — the inventory. The two answer different questions and the table is the faster one when the question is "what is in here?"

My YAML spec will not parse. What is wrong?

Tabs, nine times out of ten — YAML forbids them as indentation and the error rarely says so. After that it is an unquoted value that changed type: version: 3.0 becomes the number 3, not the string "3.0". The YAML validator reports the line, and the YAML gotchas post covers why these two account for most of it.

Can I get the endpoint list as JSON or a spreadsheet?

Copy the table and paste it into a sheet — the columns survive. For something more structured, run the spec through the JSONPath tester with an expression like $.paths..summary, which gives you a clean array of exactly the field you want.

Related tools

Further reading

• Learn OpenAPI – The OpenAPI Initiative's own introduction — the best starting point if you are about to write a spec rather than read one.
• Swagger's OpenAPI 3 documentation – Practical, example-heavy, and clearer than the specification when you just need to know how a keyword behaves.