Api Contract Validator

Automatically validate OpenAPI specs, detect breaking changes, and sync API implementation with documentation.

Install
cmdop skills install agensi-api-contract-validator

Api Contract Validator is a skill that checks whether an API implementation matches its OpenAPI or Swagger specification. It covers three distinct concerns: linting, runtime verification, and spec diffing.

For linting, it validates that a spec file follows industry standards using Spectral or Redocly, catching structural and style errors before any code ships. For runtime checks, it verifies actual server responses against the spec using Dredd or language-specific middleware, confirming that live endpoints behave as documented. For diffing, it compares two versions of a spec using oasdiff to flag breaking changes such as removed fields or altered types.

The skill provides ready-to-use configurations for GitHub Actions and GitLab CI, making it straightforward to add contract validation as a pipeline gate. Output formats include actionable reports, JUnit XML suitable for CI test result ingestion, and markdown diffs that show exactly what changed between spec versions.

Implementation-specific guidance is available for Express on Node.js, FastAPI and Flask on Python, and Go. This makes it applicable across common backend stacks without requiring separate tooling per language.

This skill is appropriate when a team maintains an OpenAPI spec alongside a live API and needs automated enforcement that the two stay consistent. It is not a general API testing framework and does not perform load testing, authentication testing, or exploratory fuzzing.

Use cases

  • Lint an OpenAPI YAML file against industry standards before merging a pull request
  • Verify that live server responses match the declared spec using Dredd
  • Detect breaking changes between two versions of an OpenAPI spec with oasdiff
  • Integrate spec validation into a GitHub Actions or GitLab CI pipeline
  • Generate JUnit XML reports from contract checks for CI test dashboards
  • Validate Express, FastAPI, Flask, or Go API implementations against their OpenAPI contracts

When to use it

  • A team maintains an OpenAPI or Swagger spec and needs automated enforcement that implementation matches documentation
  • Breaking change detection is required before promoting a new API version
  • CI/CD pipelines need a contract validation gate for GitHub Actions or GitLab CI
  • Multiple backend stacks (Node.js, Python, Go) need consistent contract checking

When not to use it

  • Load testing or performance benchmarking of API endpoints is the goal
  • Authentication, authorization, or security penetration testing is needed
  • The API does not use OpenAPI or Swagger as its specification format
  • Exploratory or fuzz testing of API inputs is required