# OpenAPI Validator Engine MCP

> OpenAPI Validator Engine validates any OpenAPI or Swagger spec (2.0, 3.x, 3.2) locally before you generate code from it. It catches structural errors—like missing references or invalid data types—and returns the exact path of every single issue. Use it as a mandatory quality gate for your API definitions.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** api-specification, swagger, schema-validation, code-generation, quality-assurance, json-schema

## Description

You're about to build code using an OpenAPI spec or Swagger definition. You don't know where the weak spot is—maybe it's a missing `$ref`, maybe you messed up a data type, or perhaps your path parameter won't map right when it hits production. Your agent might compile locally, but if the underlying schema is garbage, the whole thing crashes later.

This tool, `validate_openapi`, forces you to clean up your API specs before any code generation starts. You pass in a JSON string containing your OpenAPI or Swagger specification. The engine validates that entire spec against official industry schemas (covering versions 2.0 through 3.2). It doesn't just tell you if it passed; it tracks down every single structural error and gives you the exact path where the problem lives.

When you use `validate_openapi`, you get immediate, actionable feedback that acts as a mandatory quality gate for your API definitions. You don't have to guess where the breakage is; the tool pinpoints it for you.

It handles multiple layers of validation simultaneously. First, it determines exactly what OpenAPI version—like 2.0 or 3.1—your provided specification uses. This detection helps ensure that subsequent checks apply the correct set of rules. Next, it runs a full check against official JSON Schema standards. This process validates the entire spec's internal structure, catching fundamental mistakes like improper data typing or misformatted object definitions.

The tool pays close attention to how you define your endpoints. It specifically identifies path errors, flagging any incorrect path parameters or URL template definitions. These are the kinds of issues that look fine in a text editor but break completely when an external request hits them at runtime. You won't run into these surprises.

Another critical function is locating missing references. If your specification uses a reference (`$ref`) to point to a component—say, a reusable schema object—and that component hasn't been defined anywhere in the document, the engine finds it. It prevents you from building code based on non-existent definitions.

The output is never vague. When an error exists, `validate_openapi` doesn't just say 'error found.' It returns highly detailed reports, including specific JSON pointers for every mistake. These paths let you fix the schema in a surgical manner; you know exactly which line and key needs changing to make the definition clean.

This thorough process means your AI client gets a validated spec—one that adheres to industry standards across multiple versions (2.0-3.2). You get structural integrity for free, so your agents can focus on building features instead of debugging bad inputs.

## Tools

### validate_openapi
Pass a JSON string containing your OpenAPI/Swagger spec. The engine validates it against official schemas (2.0-3.2) and returns all structural errors with exact paths.

## Prompt Examples

**Prompt:** 
```
Before I generate the TypeScript SDK, validate this OpenAPI 3.1 spec for any schema errors.
```

**Response:** 
```
Version: 3.1.0 | Valid: false | 2 errors: missing $ref at paths./users, invalid type at components.schemas.Order.status.
```

**Prompt:** 
```
Our partner sent us their API spec. Check if it's valid before we start integration.
```

**Response:** 
```
Version: 3.0.3 | Valid: true | 0 errors. Spec is clean — safe to proceed.
```

**Prompt:** 
```
Validate our internal Swagger 2.0 spec — it was auto-generated and might have issues.
```

**Response:** 
```
Version: 2.0 | Valid: false | 5 errors in definitions and path parameters.
```

## Capabilities

### Detect Spec Version
Determines which OpenAPI version (2.0, 3.1, etc.) your provided specification uses.

### Validate Schema Structure
Checks the entire spec against official JSON Schema standards to find structural mistakes.

### Identify Path Errors
Flags incorrect path parameters or URL template definitions that won't map correctly at runtime.

### Locate Missing References ($ref)
Finds instances where the spec uses a reference (`$ref`) to a component that hasn't been defined.

### Report Error Paths
Returns detailed error reports, including specific JSON pointers to make fixing the schema straightforward.

## Use Cases

### The Partner API Contract Check
A platform architect receives a massive OpenAPI spec from an external partner. Instead of spending days manually reviewing it, they run `validate_openapi` immediately. The tool flags that the partner forgot to define the data type for a critical field in their response body. This single report saves weeks of integration friction.

### Pre-Commit Code Generation Check
A developer is about to generate an SDK using an internal spec. They suspect it's flawed. Running `validate_openapi` confirms a missing `$ref` in the components section and alerts them immediately, forcing them to fix the documentation before committing anything.

### Migrating from Swagger 2.0
A team is updating an old API that uses Swagger 2.0 definitions into OpenAPI 3.1 format. They run `validate_openapi` on the new spec, which flags several deprecated paths and incorrect schema structures specific to the migration process, guiding them through a clean upgrade.

## Benefits

- Eliminate runtime bugs by catching specification errors early. If `validate_openapi` says it's invalid, don't generate the SDK—fix the spec first. This prevents the entire class of 'it worked on my machine' failures.
- Save time debugging broken contracts. Instead of a vague error message in logs, you get a report listing errors with JSON pointers (e.g., `paths./users`), telling you exactly which line needs adjustment.
- Enforce quality gates in CI/CD pipelines. You can use the engine to reject any code generation request based on an invalid spec, making API documentation mandatory and trustworthy.
- Support multiple standards at once. It handles everything from legacy Swagger 2.0 up through OpenAPI 3.1 and 3.2, meaning you don't need a separate tool for every version.
- Speed up integration confidence. With clear validation results, your agent can move past guesswork and proceed directly to code generation with high certainty.

## How It Works

The bottom line is: you get a definitive report telling you exactly what's broken in your API spec—and where to fix it.

1. You pass the raw OpenAPI or Swagger specification as a single JSON string to the `validate_openapi` tool.
2. The engine runs an offline check, comparing the spec against official industry schemas and checking for structural integrity.
3. It returns a structured object detailing the version, overall validity status, and a list of all specific errors found with their exact paths.

## Frequently Asked Questions

**Which OpenAPI versions does it support?**
Swagger 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and OpenAPI 3.2.x. The version is auto-detected from the spec.

**Does it validate $ref references?**
Yes. The validator checks that all $ref pointers resolve to existing schema definitions. Missing or circular references are reported as errors.

**Can I use this as a CI/CD quality gate?**
Absolutely. If isValid is false, block code generation and SDK publishing. The error paths pinpoint exactly what to fix.

**When I run validate_openapi, what kind of error details do I get?**
It returns highly specific error reports, including the exact JSON pointer path for every issue. This means you don't just know *that* there's an error; you know precisely where (e.g., paths./users) and why it failed.

**Is running validate_openapi secure since I can't use external APIs?**
Yes, the validation runs entirely offline because the schema is embedded in the MCP Server. You don't make any calls to external services or APIs, keeping your data completely local.

**What format does validate_openapi require for the input spec?**
You pass the entire specification as a single JSON string. The engine then handles parsing and validates it against the official OpenAPI standards. Keep the input clean, and the validation works fast.

**How does validate_openapi perform regarding speed and performance?**
It's built for speed. Since it doesn't make external network calls, validating a large spec is quick. You get near-instant feedback on structural issues without waiting for external API responses.

**Does validate_openapi enforce the official OpenAPI JSON Schema standards?**
Absolutely. The tool validates your spec against the official JSON Schemas, guaranteeing adherence to the defined contract rules (2.0 through 3.2). It's your guarantee that the spec is structurally sound.