Input (JSON or YAML)
Validation Results
Paste a document and click Validate
OpenAPI Validator checks your OpenAPI/Swagger specification (YAML or JSON) for syntax errors, schema violations, and best-practice issues. Paste or upload an OpenAPI 2.0 (Swagger), 3.0, or 3.1 spec to validate it against the official schema, identify missing required fields, find inconsistent references ($ref), and receive actionable error messages with line numbers.
OpenAPI Specification (OAS) is the most widely used standard for describing REST APIs. An OpenAPI spec defines: info (API name, version, description), paths (endpoints with HTTP methods), request parameters and request bodies, response schemas, authentication schemes (securitySchemes), and reusable components. The spec can be auto-generated from code annotations (Swagger annotations in Java, FastAPI in Python, NestJS in TypeScript) or written by hand ('design-first' approach).
OpenAPI 3.1 (2021) aligns fully with JSON Schema Draft 2020-12, allowing any JSON Schema keyword in schemas. OpenAPI 3.0 (2017) uses a subset of JSON Schema with some modifications. Swagger 2.0 (2014) is the legacy version still used in many enterprises. Key 3.x improvements over 2.x: requestBody replaces body parameters, servers replaces host/basePath, components replaces definitions, oneOf/anyOf/allOf are fully supported.
Validate minimal spec
Result: openapi: '3.0.3' / info: {title: 'My API', version: '1.0.0'} / paths: {} → ✓ Valid
Detect missing $ref
Result: $ref: '#/components/schemas/User' → Error: Referenced schema 'User' not found in components.schemas
Lint warning
Result: GET /users has no 200 response defined → Warning: Missing success response for GET operation
What is the difference between OpenAPI 2.0 (Swagger) and OpenAPI 3.0?
OpenAPI 3.0 (2017) made several breaking changes from Swagger 2.0 (2014): requestBody replaces body parameters (cleaner separation of path/query params vs body). servers array replaces host + basePath + schemes (supports multiple servers, variables). components replaces definitions (reusable schemas, responses, parameters, examples all in one place). links define relationships between responses and operations. callbacks support webhook definitions. content negotiation improved. If starting a new project, use OpenAPI 3.1 (fully JSON Schema compatible, 2021).
What is $ref in OpenAPI and how do I use it?
$ref is JSON Reference — it points to a definition elsewhere in the spec or in an external file. Internal reference: $ref: '#/components/schemas/User' (the # means root of the current document, then navigate the JSON path). External file: $ref: './schemas/user.yaml'. External URL: $ref: 'https://example.com/schemas/user.json'. Best practice: define all reusable schemas, parameters, responses, and examples in components/schemas, then reference them with $ref to avoid duplication. This keeps the spec DRY and allows tooling to generate better types.
What is the difference between oneOf, anyOf, and allOf in OpenAPI?
allOf: the value must match ALL listed schemas — used for schema composition (extending a base schema: allOf: [{$ref: '#/components/schemas/Base'}, {properties: {extraField: {type: string}}}]). oneOf: the value must match EXACTLY ONE schema — used for discriminated unions, error types. anyOf: the value must match AT LEAST ONE schema — more permissive than oneOf. In practice: allOf for inheritance/mixin, oneOf for mutually exclusive types (with discriminator for better code generation), anyOf for flexible validation.
How do I add authentication to an OpenAPI spec?
Define securitySchemes in components: for API keys: type: apiKey, in: header, name: X-API-Key. For OAuth2: type: oauth2, flows: {authorizationCode: {authorizationUrl, tokenUrl, scopes}}. For Bearer tokens: type: http, scheme: bearer, bearerFormat: JWT. Then reference globally: security: [{BearerAuth: []}] or per-operation for specific requirements. Use security: [] on an operation to override a global scheme and make the operation public. Multiple items in security mean AND (all required); multiple security array entries mean OR.
What tools can I use to generate code from an OpenAPI spec?
API client generators: openapi-generator-cli (40+ languages), swagger-codegen, Microsoft's kiota. TypeScript: openapi-typescript generates TypeScript types without a runtime dependency; openapi-fetch uses those types with a fetch wrapper. Go: oapi-codegen generates typed server stubs and clients. Rust: progenitor. Python: openapi-python-client. Server stub generators: FastAPI reads OpenAPI at runtime and generates it; NestJS with @nestjs/swagger generates from decorators; the above generators also create server stubs. Design tools: Stoplight Studio is a visual OpenAPI editor.