OpenAPI Formatter and Validator

How to use OpenAPI Formatter and Validator

A slightly broken API spec can break the documentation page or make a code generator fail. This tool reads an OpenAPI document as YAML or JSON, checks required fields and commonly broken links between parts, and also works as a formatter by showing nicely indented JSON at the end.

It checks the openapi version and info.title and info.version, that paths start with /, that each operation has responses and each response a description, and that status codes are valid. It finds path parameters, as in /tools/{id}, that aren’t declared with in: path and required: true, and declared parameters that don’t appear in the path.

An operationId used twice is flagged as an error because generated function names would clash, and every $ref inside the document (#/components/...) is checked to point at a real target. $refs to other files are only noted.

• Paste the contents of openapi.yaml or JSON into OpenAPI document.
• Press Run to see counts of paths, operations and schemas with errors, warnings and notes, followed by the formatted JSON.
• Find the flagged operation (GET /path and so on), fix it and run again.

Useful for

• Finding why Swagger UI or Redoc renders a spec incorrectly
• Checking a spec before generating client code with OpenAPI Generator
• Converting a YAML spec to JSON for another tool
• Finding duplicate operationIds and broken $refs in a spec edited by many people

Limits and checks

• Writing info.version as 1.0 without quotes can be read as the number 1. Write it as a string, '1.0'.
• operationIds become generated function names, so unique verb-first names such as listTools or getTool work well.

Worked example

Example input: An undeclared path parameter

openapi: 3.0.3
info:
  title: Tool API
  version: '1.0'
paths:
  /tools/{id}:
    get:
      operationId: getTool
      responses:
        '200':
          description: OK

The real result continues with the full formatted JSON.

Result

1 error · 0 warnings · 0 notes
OpenAPI 3.0.3 · 1 path · 1 operation · 0 schemas

[error] GET /tools/{id}: path parameter {id} is not declared.

Formatted JSON:
{ … }

The real result continues with the full formatted JSON.

Common issues

An error that path parameter {id} isn’t declared in parameters.

Add name: id, in: path, required: true and a schema to the parameters at the operation or path level.

An error that a $ref has no target.

The name in #/components/schemas/Tool differs in spelling or case from the actual name under components. Make the two match.

How to interpret the result

Reads an OpenAPI 3.x (or Swagger 2.0) document as YAML or JSON, finds problems with info, response descriptions, undeclared path parameters, duplicate operationIds and $refs with no target, and shows it again as formatted JSON.

Related workflow

operationIds become generated function names, so unique verb-first names such as listTools or getTool work well.

Privacy and review notes

ToolBada runs this tool in your browser where it can. Use sample values instead of personal or confidential data, and review the result before relying on it.

FAQ

Does it check schema details (properties, type)?

It doesn’t validate rules inside schemas, only $ref links. For thorough validation, use a dedicated linter such as Spectral alongside.

Does it handle Swagger 2.0?

swagger: "2.0" documents are read too, with info, paths, parameter and $ref checks, though 2.0-specific fields aren’t examined in depth.

Are YAML comments kept in the formatted JSON?

JSON has no comments, so they are dropped. Keep the original YAML and use the JSON for other tools.