Swagger Spec Validator

Warnings

• gotcha This library explicitly supports Swagger 1.2 and Swagger 2.0 specifications only. It does NOT support OpenAPI 3.x. For OpenAPI 3.x validation, consider `openapi-spec-validator` (a separate library).
  Fix: Ensure your specification is Swagger 1.2 or 2.0. If using OpenAPI 3.x, switch to a compatible validator like `openapi-spec-validator`.
• gotcha The API is not considered stable and may introduce non-backwards-compatible changes in minor versions.
  Fix: Pin the library version in your `requirements.txt` or `pyproject.toml` and review changelogs when upgrading.
• gotcha `validate_spec_url` requires network access to fetch the specification. If your specification contains external `$ref` pointers (e.g., to other URLs or local files not bundled with the primary spec), `validate_spec` will also require access to resolve these references.
  Fix: Ensure network connectivity for URL validation or external references. For offline validation of `$ref` pointers, consider tools that bundle or dereference the spec first, or ensure all referenced schemas are local and resolvable within the provided spec dictionary.
• gotcha Swagger specifications (and by extension, this validator) rely on a subset of JSON Schema. Some advanced JSON Schema features like `oneOf` or `patternProperties` might not be fully supported or correctly validated.
  Fix: Be aware of potential limitations when using complex JSON Schema constructs within Swagger specifications. Manual review or supplementary validation might be necessary for such cases.

Install

• pip install swagger-spec-validator Install stable version

Imports

• validate_spec_url

  from swagger_spec_validator import validate_spec_url

• validate_spec

  from swagger_spec_validator import validate_spec

  Used for validating a Swagger specification provided as a Python dictionary.
• SwaggerValidationError

  from swagger_spec_validator.common import SwaggerValidationError

Quickstart

This quickstart demonstrates how to validate a Swagger 2.0 specification using both a URL and a Python dictionary. It uses `validate_spec_url` for remote specifications and `validate_spec` for in-memory dictionary representations, which can be loaded from local YAML/JSON files using PyYAML.

import yaml
from swagger_spec_validator import validate_spec
from swagger_spec_validator import validate_spec_url
from swagger_spec_validator.common import SwaggerValidationError

# Example 1: Validate a spec from a URL
try:
    validate_spec_url('http://petstore.swagger.io/v2/swagger.json')
    print("Petstore Swagger 2.0 spec from URL is valid!")
except SwaggerValidationError as e:
    print(f"Validation failed for URL spec: {e}")

# Example 2: Validate a spec from a Python dictionary (YAML content)
swagger_spec_content = """
swagger: '2.0'
info:
  title: 'My Simple API'
  version: '1.0.0'
host: 'api.example.com'
basePath: '/v1'
schemes:
  - https
paths:
  /users:
    get:
      summary: 'Get all users'
      responses:
        '200':
          description: 'A list of users'
"""

try:
    spec_dict = yaml.safe_load(swagger_spec_content)
    validate_spec(spec_dict)
    print("Local Swagger 2.0 spec (dictionary) is valid!")
except SwaggerValidationError as e:
    print(f"Validation failed for local spec: {e}")
except Exception as e:
    print(f"An error occurred: {e}")