Why Preview OpenAPI Specs
OpenAPI specifications — whether YAML or JSON — define your API's endpoints, request/response schemas, authentication methods, and examples. But a 500-line OpenAPI YAML file is dense and hard to review. A preview renders it into structured, navigable documentation — the same experience your API consumers will see. Preview before publishing to catch incorrect schemas, missing parameters, bad examples, and structural issues.
OpenAPI vs. Swagger
Swagger 2.0 is the predecessor to OpenAPI 3.x. Most tools support both, but OpenAPI 3.x adds significant improvements: reusable components, oneOf/anyOf schema composition, better examples, cookie authentication, and linked operation descriptions. If you're starting a new API spec, use OpenAPI 3.1 — it's fully aligned with JSON Schema 2020-12 and is the current standard.
Reading an OpenAPI Spec
An OpenAPI document has a few key sections:
- info: API title, version, description, and contact. Sets the header for your docs.
- servers: Base URLs for the API — can define separate production and sandbox servers.
- paths: Every endpoint with HTTP method, parameters, request body, and response schemas. This is the bulk of the spec.
- components: Reusable schemas, parameters, responses, and security definitions. The DRY (Don't Repeat Yourself) section of your spec.
- security: Authentication methods — API key, HTTP Bearer, OAuth2, OpenID Connect.
Common Spec Errors
- Missing required fields: Every path must have at least one response, and every response must have a description.
- $ref resolution failures: Reference points to a path that doesn't exist in components. The spec breaks silently — some validators catch this, some don't.
- Example doesn't match schema: The example response JSON doesn't validate against the declared schema. Your API consumers will be confused.
- YAML indentation errors: YAML is whitespace-sensitive. A 1-space off indentation changes the structure of your spec entirely.
- Unused security schemes: Schemes defined in components/securitySchemes but never referenced in the security section.
Preview Your API Spec
Paste your OpenAPI or Swagger YAML/JSON into ToolsVito's OpenAPI / Swagger Preview to see rendered endpoints, request/response schemas, and examples in a clean documentation layout. Catch errors before your API consumers do. All processing in your browser.