OpenAPI Formatter & Validator

API developers and platform engineers use this tool when a Swagger or OpenAPI document arrives from a code generator, a Postman export, or a teammate's pull request and needs a quick structural check before it goes into the docs pipeline. It is particularly handy during spec-first API design, where a missing responses block or an unversioned info object would silently break Swagger UI rendering downstream. Technical writers also rely on it to reformat sprawling YAML specs into clean JSON they can paste into documentation templates. Because validation runs entirely in your browser, specs containing internal base URLs, pre-release endpoints, and authentication details never leave your machine.

OpenAPI / Swagger Spec (JSON or YAML)

Formatted JSON Output

Indent:

How the Validator Parses and Checks Your Specification

The first step is format detection. Input starting with { or [ is parsed with JSON.parse(); everything else routes to a hand-written YAML converter that walks indented lines, builds nested objects and arrays, and handles block scalars, quoted strings, and the YAML boolean/null keywords. A JSON syntax failure stops the run immediately with the parser's error message before any structural checks execute.

Once the document exists as a plain JavaScript object, version detection reads the openapi or swagger root field. Validation then runs a series of ordered checks. The first pass covers root-level requirements — version field presence, semver pattern on the openapi string, info object with title and version, and a non-empty paths object. The second pass iterates every path key: it must start with /, curly braces must be balanced, and at least one HTTP method should be present.

For each operation found, the validator confirms a responses object exists and that every inline parameter declares both a name and an in field. A third pass inspects components.schemas (or definitions for Swagger 2.0) and warns about schemas with no type or structural keywords. Softer warnings cover missing servers arrays on 3.x specs and the presence of legacy definitions alongside modern components. Each issue records severity (error vs warning) and a JSON Pointer path so you can navigate to the exact node.

The formatter stage re-serializes the parsed object with your chosen indentation — 2-space, 4-space, or tab. Because serialization operates on the parsed object rather than the raw text, formatting is stable regardless of input style. The stats row is computed during the validation walk: paths and operations are counted from the paths object, schemas from components, and responses summed across all operations. The entire pipeline is synchronous, local, and makes no fetch calls with your content.

Before and After Validation Examples

Example 1 — Spec with missing responses (before fix)

YAML input:

openapi: "3.0.3"
info:
  title: User API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: List users

Validator output:

⚠ Error   paths./users.get.responses — Operation GET /users is missing a "responses" object
⚠ Warning servers — No "servers" array defined — API base URL is unknown

Example 2 — After fix, formatted JSON output

Corrected input (responses added):

openapi: "3.0.3"
info:
  title: User API
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Formatted output (2-space indent):

{
  "openapi": "3.0.3",
  "info": {
    "title": "User API",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://api.example.com/v1" }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "responses": {
          "200": {
            "description": "A list of users",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/User" }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" }
        }
      }
    }
  }
}

Stats: Version OpenAPI 3.0.3 · Paths 1 · Operations 1 · Schemas 1 · Responses 1

Example 3 — Broken input reports a parse error

JSON input with a trailing comma:

{
  "openapi": "3.0.3",
  "info": { "title": "API", "version": "1.0.0", },
  "paths": {}
}

Validator output:

✗ JSON parse error: Unexpected token } at position 72

Where Teams Use This Formatter

Developer

Validate a spec generated by an OpenAPI codegen tool before committing it to the repository.
Catch a missing responses block that would cause Swagger UI to render an empty operation panel.
Convert a colleague's YAML spec to formatted JSON so you can diff it against your version in a PR.
Check that a Postman-to-OpenAPI export preserved all paths and operations before publishing docs.

Production

Gate spec changes in CI by validating the file structurally before merging to main.
Use the stats row as a quick health check — a sudden drop in operations count signals a lost path item.
Reformat specs before importing them into Stoplight or Redoc so the rendered docs are consistent.
Verify a spec version bump (3.0 to 3.1) did not drop required fields during migration.

Workflow

Paste a spec from Slack, validate it, then share the formatted output with the team.
Pair with the cURL Generator: validate the spec, then build request commands for its endpoints.
Run the YAML Validator first if the input uses advanced YAML features, then validate structure here.
Feed the formatted JSON into the JSON Schema Validator to check individual component schemas.

Common Mistakes and Troubleshooting

info.version written as a bare number

In YAML, version: 1.0 parses as a float, but the OpenAPI specification requires info.version to be a string. Quote it: version: "1.0.0". The validator does not flag this specific type, but downstream tools like Swagger UI may display the version incorrectly or reject the spec during stricter validation.

Path keys missing the leading slash

Every key under paths must start with /. Writing users: instead of /users: produces a spec that parses but fails at runtime when the router constructs URLs. The validator reports this as an error with the exact path key so you can add the missing slash.

Operation defined without responses

A method entry with only a summary and no responses block is the most common structural error. OpenAPI requires at least one response per operation. Add a 200 (for reads), 201 (for creates), or a default response with a description so documentation generators have content to render.

Mixing Swagger 2.0 keys in a 3.x document

Porting a 2.0 spec to 3.x but leaving host, basePath, definitions, or body parameters in place causes partial validation. Migrate host/basePath into a servers array, move definitions into components.schemas, and convert body parameters to requestBody. The validator warns when definitions appear without a components block.

YAML block scalars and multiline descriptions

Description fields using | or > block scalars are handled by the built-in converter, but indentation inside the block must be consistent. If a description contains lines indented differently than the block's base indent, the converter may fold them into the next key. Validate after editing multiline descriptions to confirm the structure still parses.

Tabs in YAML input

YAML forbids tabs for indentation — only spaces are allowed. A spec copied from an editor configured with tabs will fail the YAML converter with an indentation error. Convert tabs to spaces in your editor (VS Code shows this in the status bar) before pasting, or paste the spec as JSON instead, where tabs inside string values are harmless.

Spec Authoring Best Practices

✓ Declare servers explicitly: include a servers array in 3.x specs so consumers know the base URL without guessing from examples.
✓ Describe every operation: add summary and description fields — they feed directly into Swagger UI, Redoc, and generated client comments.
✓ Reuse with components: move shared request and response shapes into components.schemas and reference them with $ref instead of duplicating inline.
✓ Version the spec honestly: keep info.version in sync with your release process so consumers can detect breaking changes.

Workflow and Security Tips

✓ Validate before every merge: add a spec validation step to CI so structural errors never reach the published docs.
✓ Format consistently: pick one indentation style (2-space is the community norm) and reformat on save so diffs stay readable.
✓ Specs stay local: this tool makes no network calls with your content, so internal hostnames and pre-release endpoints are safe to paste.
✓ Chain your API tools: validate here, then build requests with the cURL Generator and inspect responses with the JSON Formatter.

Frequently Asked Questions

What is the difference between Swagger 2.0 and OpenAPI 3.x? ▼

Swagger 2.0 was the last version under the Swagger name before the specification was donated to the OpenAPI Initiative and renamed. OpenAPI 3.0 restructured how you describe servers, request bodies, and security — the host/basePath fields became a servers array, body parameters moved into a requestBody object, and components replaced the definitions/parameters/responses top-level keys. OpenAPI 3.1 aligned the schema vocabulary with JSON Schema 2020-12. This tool detects which version you pasted and applies version-appropriate checks.

Does this validator catch every OpenAPI spec error? ▼

It catches the structural mistakes that break most tooling: missing openapi or swagger version field, missing info.title or info.version, missing or empty paths, paths not starting with a slash, operations without a responses object, and parameters missing name or in. It also warns about softer issues like missing servers or schemas without a type. Full JSON Schema validation of the entire spec against the official meta-schema is not performed — use the official Swagger validator for that depth.

Why does the tool report an error for my responses field? ▼

Every operation in OpenAPI 3.x must declare at least one response, and the most common mistake is defining a path with a method but no responses block. The validator flags each method that lacks responses because Swagger UI, Redoc, and code generators all fail or render empty docs when this field is absent. Add at least a default or a 200 response with a content schema to satisfy the requirement.

Can I paste YAML instead of JSON? ▼

Yes. The tool auto-detects the format: input starting with { or [ is parsed as JSON, anything else goes through a built-in YAML-to-JSON converter. The converter handles nested mappings, sequences, block scalars (| and >), quoted strings, numbers, booleans, and null. After validation, the output pane always shows formatted JSON with your chosen indentation so you can diff or embed it directly.

What do the statistics counters mean? ▼

The stats row summarizes the parsed document: paths counts distinct URL templates under the paths object, operations counts individual method entries (get, post, put, etc.) across all paths, schemas counts entries in components.schemas (or definitions for Swagger 2.0), parameters counts inline operation parameters, and responses counts declared responses across all operations. A large gap between paths and operations often means some path items have no methods defined.

Is my API specification uploaded to a server? ▼

No. Parsing, validation, and formatting all run in your browser using local JavaScript. The tool issues no network requests carrying your spec. This matters because API specifications frequently contain internal hostnames, pre-release endpoints, authentication scheme details, and business logic descriptions that should not be sent to third-party services.

How do I fix a spec that fails validation? ▼

Read the error list — each entry includes a JSON Pointer path like paths./users.get.responses that tells you exactly which node to open. Common fixes: add an info.version string, add a responses object to the flagged operation, ensure every path key starts with /, and confirm the openapi field uses a value like 3.0.3 rather than a custom string. After fixing, re-run validation until the list is empty, then copy the formatted output.