An OpenAPI document describes an API's declared interface. It helps you find operations, parameters and responses without reading every line of JSON or YAML. It does not, by itself, prove that a running server behaves as described or that the API is secure.
ToolsOnDuty OpenAPI Viewer performs focused structural checks and presents inspectable operations locally in the browser. This guide uses its sample inventory API, then changes one path parameter to demonstrate a real finding. The screenshots show actual inspection results, not a fabricated successful API request.
Start with the right document
The viewer supports OpenAPI 3.0 and 3.1 documents in UTF-8 JSON or YAML. An ordinary JSON response from an API is not an OpenAPI specification. Look for the top-level openapi version and the document's info and API structure before expecting an endpoint listing.
Open OpenAPI Viewer, use Open a specification to select a file or paste into JSON or YAML, then click Inspect specification. Use Try example for the reproducible inventory document. The tool does not contact declared servers or retrieve external references, so you can inspect a document without accidentally sending a request to its production API.
Understand the sample inventory endpoint
The example describes Sample inventory API version 1.0.0 using OpenAPI 3.1.0. It declares GET /items/{id}, an operation ID of getItem, the Inventory tag, a required path parameter named id and two responses: 200 Item found and 404 Item not found.
Here is a shortened standalone version of that structure. The declared example.com server is documentation data, not a service called by this tool. The response descriptions are labels; they do not provide a complete response schema or demonstrate real returned data.
openapi: 3.1.0
info:
title: Sample inventory API
version: 1.0.0
servers:
- url: https://api.example.com
paths:
/items/{id}:
get:
summary: Find an inventory item
operationId: getItem
tags: [Inventory]
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Item found
'404':
description: Item not foundRead the operation rather than only the summary
- Check the document title, API version and OpenAPI version in the status panel.
- Read the structural error and warning counts. Zero findings means no problems found by the checks performed, not full conformance.
- Expand GET /items/{id} to inspect the operation ID, tags, parameters and response descriptions.
- Confirm that id is listed as a required path parameter and that the expected response codes are present.
- Use Find an endpoint and the Method filter for larger documents. Pagination displays up to 25 matching operations per page.
Reproduce a required path-parameter error
In the pasted sample, change required: true to required: false for the parameter whose name is id and whose location is path. Click Inspect specification again. The viewer should report one structural error stating that path parameters must have required: true.
The finding includes a document pointer to the affected parameter. This helps distinguish an invalid parameter declaration from an unrelated response or server entry. Restore required: true and inspect again to confirm that this specific finding disappears. Rechecking after a correction is more useful than assuming that editing one line repaired every potential issue.
Path placeholders identify part of the URL itself. An operation using /items/{id} needs that path value to identify the requested resource. Do not 'fix' the finding by merely deleting the parameter declaration if the actual API still requires it; keep the contract consistent with intended behavior.
References and endpoint coverage have limits
OpenAPI documents often use references to avoid repeating components. The viewer can inspect supported local references, but it does not fetch external reference documents. A multi-file specification may therefore need a suitable bundling step before it can be inspected completely here.
The operation listing focuses on ordinary paths. Callbacks and webhooks are not listed, and a component-only or webhook-only document can legitimately show no ordinary path operations. An empty search result can also be caused by the selected method or endpoint filter, so clear filters before concluding that the document has no endpoints.
Descriptions are presented as plain text rather than executed HTML. The viewer is for reading the contract, not running embedded instructions, issuing API calls or trying authorization credentials.
Use the viewer alongside proper validation and testing
Focused structural checks are useful for spotting obvious mistakes quickly. They are not a substitute for a complete OpenAPI conformance validator, JSON Schema validation, lint rules agreed by your team or tests against the actual API.
For an important API change, check the document with the appropriate full validator, review compatibility with existing clients and test representative requests in an authorized environment. Confirm request and response schemas, authentication behavior and failure handling separately. Neither a zero-error panel nor a readable endpoint list establishes security, production readiness or backward compatibility.
Troubleshoot parsing and oversized documents
Avoid pasting real API tokens or private examples into documentation unnecessarily. Local processing does not prevent screenshots, browser extensions or copied excerpts from exposing information. Keep a reviewed source document in version control and treat viewer results as one part of your workflow.
- A parse error: check JSON punctuation or YAML indentation before interpreting it as an API-contract problem.
- No operations: clear filters, inspect paths and check whether the document only defines components or webhooks.
- An unresolved reference: determine whether it is external or outside the supported local reference structures.
- A rejected file: input is limited to 5 MiB, 100,000 values, 10 million expanded text characters, 64 levels and 5,000 operations.
- A legacy Swagger document: this viewer targets OpenAPI 3.0 and 3.1; use a suitable migration or validator for other specification versions.
Try the related tools
Apply the steps from this guide directly in your browser.
Frequently asked questions
Does inspecting a specification call its server?
No. Declared server URLs are displayed, not contacted. External references are not fetched either.
Does zero structural errors mean full OpenAPI compliance?
No. It means the focused checks performed found no structural errors. Use a complete validator and appropriate tests for broader assurance.
Why can a valid-looking document show no endpoints?
It may have no ordinary paths, contain only components or webhooks, or be hidden by active filters. Callbacks and webhooks are not included in the operation listing.
Can this replace testing my API responses?
No. A specification describes intended behavior. Actual response schemas, authentication and runtime failures require authorized API testing.
