About OpenAPI Viewer
An OpenAPI document describes an HTTP API in a machine-readable way: its paths, operations, parameters, request and response schemas, and security schemes. This viewer renders one so you can read it, which is considerably easier than scrolling a few thousand lines of YAML.
Version matters when things do not work. OpenAPI 3.0 and 3.1 look similar but differ in ways that break tooling: 3.1 aligns with JSON Schema 2020-12, replaces the 3.0 `nullable: true` flag with a type array (`type: [string, null]`), and allows webhooks as a top-level concept. Many generators still only fully support 3.0, so a valid 3.1 document can fail in a tool that claims OpenAPI support.
The two features that cause the most confusion are $ref and discriminators. A $ref can point within the document or to an external file or URL, and resolution is relative to the referring document - which is why a spec that renders in one tool fails in another that resolves paths differently. Discriminators, used with oneOf to indicate which variant a payload is, are frequently written in a way that validators accept and code generators cannot use.
The most useful discipline with OpenAPI is deciding whether the document is generated from the code or the code is generated from the document. Either works; what does not work is maintaining both by hand, because they drift silently and the specification becomes confidently wrong - which is worse than having none at all.
Rendering happens in your browser, so an internal API specification is not uploaded.
How to use the OpenAPI Viewer
- Paste the OpenAPI document, in JSON or YAML.
- Browse the paths and operations, and expand the schemas you care about.
- Check the declared version - 3.0 and 3.1 differ in nullable handling and JSON Schema alignment.
- If a $ref does not resolve, check whether it is external and whether the path is relative to this document.
OpenAPI Viewer in code
The same operation this tool performs, in the languages you are most likely to need it.
# Validate
npx @redocly/cli lint openapi.yaml
npx @apidevtools/swagger-cli validate openapi.yaml
# Bundle external $refs into one self-contained file - do this
# before handing the spec to a tool that resolves refs poorly
npx @redocly/cli bundle openapi.yaml -o bundled.yaml
# Generate a client
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml -g typescript-fetch -o ./client
# Static documentation
npx @redocly/cli build-docs openapi.yaml -o docs.html
# Check for breaking changes between two versions in CI
npx oasdiff breaking old.yaml new.yaml# OpenAPI 3.0: nullable is a separate flag
components:
schemas:
User:
type: object
properties:
name: { type: string }
deletedAt:
type: string
format: date-time
nullable: true # 3.0 only
# OpenAPI 3.1: JSON Schema 2020-12, so use a type array
deletedAt:
type: [string, "null"] # 3.1; nullable is GONE
# 3.1 also adds top-level webhooks, allows sibling keys next to
# $ref, and uses "examples" (plural) in schemas. A generator that
# only understands 3.0 will fail or silently mishandle all of these.When you need this
- Reading an API specification without scrolling through raw YAML.
- Checking exactly what a request body or response schema requires.
- Confirming which security scheme an operation uses.
- Reviewing a spec change before it is merged.
Common problems and what causes them
- 3.0 nullable versus 3.1 type arrays
- nullable: true exists only in 3.0. In 3.1 you write type: [string, "null"]. Using the wrong form for your declared version means validators and generators quietly treat the field as non-nullable.
- External $refs that do not resolve
- A $ref to another file or URL is resolved relative to the referring document, and tools differ in how they handle it. Bundle the spec into one self-contained file before feeding it to a generator.
- Specification drifting from the implementation
- A hand-maintained spec alongside hand-written handlers diverges within weeks, and a confidently wrong specification is worse than none. Generate one from the other, and check the result in CI.
- Discriminators that generators cannot use
- A oneOf with a discriminator needs the property to be required and present in every variant, with mapping keys matching the schema names. Validators are more forgiving than code generators, so a spec can validate and still produce unusable clients.
- Examples that do not match their schema
- Most tools do not validate examples against the schema they illustrate, so they rot silently and mislead anyone reading the docs. Lint for it - Redocly can check this.
- Missing error responses
- Specs commonly document only the 200 case. Clients generated from them have no types for errors, and consumers have no idea what a 4xx body looks like. Document the failures too.
FAQ
- What is the difference between OpenAPI 3.0 and 3.1?
- 3.1 aligns with JSON Schema 2020-12, which removes the nullable flag in favour of type arrays, allows sibling keys alongside $ref, and adds top-level webhooks. The practical consequence is that tooling support lags - a valid 3.1 document can fail in generators that only handle 3.0.
- What happened to Swagger?
- Swagger 2.0 was renamed OpenAPI when the specification moved to the OpenAPI Initiative in 2016. 'Swagger' now refers to the tooling - Swagger UI, Swagger Codegen - while the specification is OpenAPI. Swagger 2.0 documents are still common and are not directly compatible with 3.x.
- Should I write the spec first or generate it from code?
- Either is workable; maintaining both by hand is not. Spec-first gives you a contract to design and review against before implementing; code-first keeps the document automatically accurate. Whichever you choose, verify in CI that they agree.
- Why won't my $ref resolve?
- External references are resolved relative to the referring document and tools implement this inconsistently. Bundle everything into a single self-contained file - redocly bundle - before handing it to a generator.