Registry / testing / swagger-spec-validator

swagger-spec-validator

library3.0.4pypypi✓ verified 22d ago

Swagger Spec Validator is a Python library that validates Swagger Specs against the Swagger 1.2 or Swagger 2.0 specification. The validator aims to check for full compliance with the Specification. It is currently in active maintenance, with version 3.0.4 released in June 2024.

testing serialization

pip install swagger-spec-validator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SWAGGER-SPEC-VALID

swagger-spec-validator

testingpythonv3.0.4

Install

2.6s avg

Import

453ms

Disk

23MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.464s · 24.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.442s · 25MB

23MB installed

● package 23MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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}")

swagger-spec-validator --version

Debug

Known issues

gotchaThis 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`.

affects: All versions

gotchaThe 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.

affects: All versions

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.

affects: All versions

gotchaSwagger 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.

affects: All versions

Errors

Common errors & fixes

ValueError: Unsupported swagger version '3.0'

The `swagger-spec-validator` library only supports Swagger 1.2 and Swagger 2.0 specifications, not OpenAPI 3.x.

fix

For OpenAPI 3.x specifications, use a dedicated validator library like `openapi-spec-validator` or `pydantic-openapi-spec`. Ensure your input specification is Swagger 1.2 or 2.0 if using `swagger-spec-validator`.

ModuleNotFoundError: No module named 'swagger_spec_validator.validator20'

Users are attempting to import internal modules (like `validator20` or `validator12`) directly, which are not part of the public API and should not be accessed this way.

fix

Import `validate_spec` from the top-level `swagger_spec_validator` package and use it to validate the specification, passing the version as an argument:
```python
from swagger_spec_validator import validate_spec
# For Swagger 2.0
validate_spec(your_spec_dict, '2.0')
# For Swagger 1.2
validate_spec(your_spec_dict, '1.2')
```

SwaggerValidationError

The provided Swagger specification does not conform to the chosen Swagger 1.2 or 2.0 standard, and the validator found one or more issues.

fix

Catch the `SwaggerValidationError` exception and examine its detailed message to identify and correct the specific non-compliance issues within your Swagger specification:
```python
from swagger_spec_validator import validate_spec, SwaggerValidationError

try:
    validate_spec(your_spec_dict, '2.0')
    print("Specification is valid!")
except SwaggerValidationError as e:
    print(f"Specification validation failed: {e}")
    # The 'e' object contains details about the validation errors.
```

Upgrade

Version history

3.0.4latest on PyPI · released Jun 27, 2024

Audit

Dependencies

jsonschemarequiredRequired for underlying JSON schema validation.

PyYAMLrequiredUsed for parsing YAML-formatted Swagger specifications.

importlib_resourcesrequiredRequired for Python 3.9+ for resource loading.

Agent activity

5 hits · last 30 days

node

Resources

githubhttp://github.com/Yelp/swagger_spec_validator ↗

packagehttps://pypi.org/project/swagger-spec-validator/ ↗

homepagehttp://swagger.io ↗