Swagger Validator

Swagger/OpenAPI Specification (JSON or YAML)

Paste or type your Swagger/OpenAPI specification to validate

How It Works

Step 1: Paste Swagger/OpenAPI specification in JSON or YAML format including paths, operations (GET, POST), parameters, request/response schemas, and security definitions.
Step 2: The validator parses specification against OpenAPI 2.0 (Swagger) or OpenAPI 3.0/3.1 standards, checking required fields (openapi version, info, paths), valid HTTP methods, and schema definitions.
Step 3: Validates schema structure including parameter types (string, integer, array), required fields, enum values, response codes (200, 404, 500), and $ref references to components.
Step 4: Provides validation report with errors (missing required fields, invalid types), warnings (deprecated features, security issues), and suggestions for API design best practices.

Manual vs Automated Swagger Validation

Feature	Manual Review	AI-Powered Validator
Spec Validation	Manually check OpenAPI structure	Instant validation against OpenAPI 2.0/3.0/3.1
Format Support	Separate tools for JSON and YAML	Auto-detects and validates both formats
Error Detection	Miss required fields until API fails	Catches missing info, paths, schemas immediately
Reference Checking	Manually verify $ref paths	Validates all $ref references automatically
Schema Compliance	Read OpenAPI spec documentation	Built-in OpenAPI standard validation
API Design	No feedback on best practices	Suggests improvements for API design

Swagger Validation Examples

Example 1: OpenAPI Specification Validation

Invalid Swagger Input

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
      responses:
        201:
          description: Created
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string

Validation Report Output

Validation Report:

❌ ERRORS (2):

Path: /users POST
  Missing response schema for 201 status code
  Location: paths./users.post.responses.201
  Fix: Add 'content' and 'schema' to response definition

Components: schemas.NewUser
  Referenced schema 'NewUser' is not defined
  Location: paths./users.post.requestBody.content.application/json.schema.$ref
  Fix: Define 'NewUser' schema in components.schemas

⚠️ WARNINGS (3):

Path: /users GET
  Missing security definition
  Recommendation: Add security requirement for authentication

Path: /users POST
  No error response (4xx, 5xx) defined
  Recommendation: Add 400 (Bad Request) and 401 (Unauthorized) responses

General:
  Missing 'servers' field
  Recommendation: Define API base URL in 'servers' array

✅ VALID SPECIFICATION (After Fixes):

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: Get all users
      security:
        - bearerAuth: []
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        401:
          description: Unauthorized
    post:
      summary: Create user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        400:
          description: Bad Request
        401:
          description: Unauthorized
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
    NewUser:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        email:
          type: string
          format: email
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Summary:
  OpenAPI Version: 3.0.0
  Total Paths: 1
  Total Operations: 2
  Errors: 0 (after fixes)
  Warnings: 0 (after fixes)
  Compliance: 100%

Key Changes:

The validator enforces OpenAPI 3.0 specification compliance, catching critical errors that would break API documentation tools like Swagger UI or code generators. The missing 'NewUser' schema definition causes $ref resolution failure—clients can't generate request models without the schema. The 201 response lacks content/schema, preventing documentation of the created resource structure. The validator recommends security definitions (bearerAuth) to document authentication requirements—essential for API consumers to understand access control. Missing error responses (400, 401) are flagged as warnings—production APIs should document error cases for proper error handling in client code. The 'servers' field absence means no base URL is documented, forcing developers to guess the API endpoint. After fixes, the specification is complete with JWT authentication, comprehensive error responses, and proper schema definitions. API teams use Swagger validators in CI/CD pipelines to enforce API design standards, prevent breaking changes, and ensure documentation accuracy before deployment. Valid OpenAPI specs enable automatic client SDK generation (TypeScript, Python, Java) and API testing with tools like Postman or Insomnia.

Example 2: YAML Syntax and Schema Validation

Swagger 2.0 YAML (Invalid) Input

swagger: 2.0
info:
  title: Product API
  version: 1.0
basePath: /api
paths:
  /products/{id}:
    get:
      parameters:
        - name: id
          in: path
          type: string
      responses:
        200:
          description: Product found
          schema:
            $ref: '#/definitions/Product'
        404
          description: Not found
definitions:
  Product:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      price
        type: number

Validation Report Output

Validation Report:

❌ CRITICAL ERRORS (3):

Line 18: YAML Syntax Error
  Missing colon after '404'
  Location: paths./products/{id}.get.responses.404
  Fix: Change '404' to '404:'
  
Line 28: YAML Syntax Error
  Missing colon after 'price'
  Location: definitions.Product.properties.price
  Fix: Change 'price' to 'price:'

Path Parameter Validation:
  Parameter 'id' in path requires 'required: true' property
  Location: paths./products/{id}.get.parameters[0]
  Fix: Add 'required: true' to path parameter definition

⚠️ WARNINGS (2):

Path: /products/{id}
  No error responses defined (401, 500)
  Recommendation: Add authentication error (401) and server error (500) responses

Definitions: Product
  No 'required' fields specified
  Recommendation: Mark mandatory fields as required for validation

✅ CORRECTED SPECIFICATION:

swagger: "2.0"
info:
  title: Product API
  version: "1.0"
  description: RESTful API for product management
basePath: /api
produces:
  - application/json
paths:
  /products/{id}:
    get:
      summary: Get product by ID
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: Product identifier
      responses:
        200:
          description: Product found
          schema:
            $ref: '#/definitions/Product'
        404:
          description: Product not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/Error'
definitions:
  Product:
    type: object
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
        minLength: 1
      price:
        type: number
        format: double
        minimum: 0
  Error:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: integer
      message:
        type: string

Validation Summary:
  Swagger Version: 2.0
  Syntax Errors: Fixed (YAML colons)
  Schema Compliance: 100%
  Best Practices: Applied

Key Changes:

YAML syntax errors are the most common Swagger validation failures. Missing colons after response codes (404 vs 404:) and property names (price vs price:) break YAML parsing before OpenAPI validation even begins. The validator's two-phase approach catches these early—YAML parser errors appear first, then OpenAPI schema validation runs. The path parameter 'id' must have 'required: true' for path parameters per OpenAPI 2.0 spec, unlike query parameters where it's optional. Swagger 2.0 uses 'definitions' for schemas (OpenAPI 3.0 uses 'components/schemas'), requiring $ref format '#/definitions/ModelName'. The corrected specification adds comprehensive error responses—404 for resource not found, 500 for server errors—essential for client error handling. The 'required' array in schema definitions enforces mandatory fields during request validation in API gateways like Kong or AWS API Gateway. Format specifiers (int64, double) provide type hints for code generators to use appropriate data types (Python's int vs Java's Long). The 'produces' field declares response content types, defaulting to application/json for REST APIs. Validators catch these issues before deployment, preventing runtime errors in production when API clients encounter invalid responses or missing required fields.

Frequently Asked Questions

What is Swagger/OpenAPI and why validate it?

Swagger, now standardized as OpenAPI Specification, is a machine-readable format for describing RESTful APIs using JSON or YAML. It defines API endpoints (paths), HTTP methods (GET, POST, PUT, DELETE), request parameters, response schemas, authentication methods, and data models. Validation ensures your specification conforms to OpenAPI 2.0, 3.0, or 3.1 standards, preventing errors when using tools like Swagger UI for documentation, Swagger Codegen for client SDK generation, or API testing tools like Postman. Invalid specs break these tools, causing deployment failures, incomplete documentation, and broken client libraries. Common use cases include API-first development workflows, contract testing between frontend and backend teams, and automated API documentation generation for developer portals.

How does the Swagger validator detect specification errors?

The validator uses a multi-stage parser that first validates JSON/YAML syntax, then checks OpenAPI schema compliance. It verifies required top-level fields (openapi version, info object with title and version, paths object), validates data types for each field (strings, integers, booleans, arrays, objects), checks $ref references resolve to defined components, ensures HTTP methods use valid verbs (get, post, put, delete, patch, options, head), validates response codes are numeric (200, 404, 500), and verifies schema definitions follow JSON Schema Draft specifications. For example, it catches missing required fields like info.title, invalid response structures lacking content or schema properties, and broken $ref paths like #/components/schemas/MissingModel. The validator also checks security scheme definitions, parameter locations (query, path, header, cookie), and media type declarations.

Is my Swagger specification secure during validation?

Yes, completely secure. This validator runs 100% client-side in your browser using JavaScript. Your Swagger specification never leaves your device—no network requests are made to external servers, no data is uploaded, stored in databases, logged to files, or transmitted to third parties. All parsing and validation happens in your browser JavaScript engine using local memory. This makes it safe for validating proprietary API specifications, internal company APIs with sensitive endpoint information, or APIs containing authentication details. After you close the browser tab, all data is cleared from memory. For maximum security when validating highly sensitive specifications, you can disconnect from the internet and the validator continues working offline since it requires no server connection.

Related API Tools

Related Tools & Resources

JSON Validator

Validate JSON syntax

YAML Validator

Validate YAML syntax

GraphQL Formatter

Format GraphQL queries