openapi-validator

A CLI tool that validates whether OpenAPI 3.x endpoints are executable — meaning they exist and respond on a real server.

It does not validate functional correctness or response schema conformance. It only checks reachability and classifies each endpoint by its HTTP response. The primary output is an executable boolean per endpoint: true means the path/method exists on the server.

Requirements

Bun >= 1.0.0

Installation

bun add -g @jnrdhn/openapi-validator

Or run without installing:

bunx @jnrdhn/openapi-validator --spec ./api.yaml

Usage

openapi-validator --spec <path-or-url> [options]

Options

| Flag | Alias | Description | Default | |---|---|---|---| | --spec | -s | Path or URL to OpenAPI spec (JSON or YAML) | required | | --base-url | -b | Override the base URL from the spec's servers[] | — | | --auth | | Authentication (see formats below) | none | | --header | | Extra request header, repeatable | — | | --output | -o | Output report path | report.json | | --concurrency | -c | Number of parallel requests | 3 | | --timeout | | Request timeout in milliseconds | 10000 | | --only-tag | | Only test endpoints with this tag, repeatable | — | | --skip-tag | | Skip endpoints with this tag, repeatable | — | | --skip-deprecated | | Skip deprecated endpoints | — | | --help | -h | Show help | — |

Auth formats

--auth bearer:<token>
--auth apikey:<HeaderName>:<value>
--auth basic:<username>:<password>

Examples

# Local spec with base URL override
openapi-validator --spec ./petstore.yaml --base-url http://localhost:3000

# Remote spec with bearer token
openapi-validator --spec https://api.example.com/openapi.json --auth bearer:mytoken

# API key auth, custom output path
openapi-validator --spec ./api.yaml --auth apikey:X-Api-Key:secret --output results.json

# Basic auth, only test endpoints tagged "users"
openapi-validator --spec ./api.yaml --auth basic:admin:password --only-tag users

# Extra headers (e.g. tenant ID)
openapi-validator --spec ./api.yaml --header "X-Tenant-ID:acme" --header "X-Api-Version:2"

# Skip deprecated endpoints and a specific tag
openapi-validator --spec ./api.yaml --skip-deprecated --skip-tag internal

Status classification

Each endpoint is classified into one of these statuses:

| Status | HTTP codes | executable | Meaning | |---|---|---|---| | valid | 2xx | true | Endpoint responded successfully | | bad_request | 400, 422 | true | Endpoint exists, but synthetic test params were rejected | | unauthenticated | 401 | true | Endpoint exists, requires credentials | | forbidden | 403 | true | Endpoint exists, credentials lack permission | | not_found | 404 | false | Endpoint path does not exist on the server | | method_not_allowed | 405 | false | HTTP method not supported for this path | | server_error | 5xx | false | Server-side error | | unreachable | network/timeout | false | Server did not respond | | error | other | false | Unexpected HTTP status |

executable: true is the primary signal — it means the path/method exists on the server, even if the request failed due to auth or bad params.

Output

Results are written to report.json (or the path set by --output). The report contains:

{
  "timestamp": "2024-01-01T00:00:00.000Z",
  "spec": { "title": "My API", "version": "1.0.0", "baseUrl": "https://api.example.com" },
  "totalEndpoints": 42,
  "summary": {
    "valid": 10,
    "bad_request": 15,
    "unauthenticated": 8,
    "forbidden": 2,
    "not_found": 3,
    "method_not_allowed": 0,
    "server_error": 1,
    "unreachable": 0,
    "error": 3,
    "executable": 35,
    "not_executable": 7
  },
  "results": [
    {
      "method": "GET",
      "path": "/users",
      "status": "valid",
      "executable": true,
      "httpStatusCode": 200,
      "durationMs": 142,
      ...
    }
  ]
}

How it works

1. Loads the OpenAPI spec (JSON or YAML, local file or URL)
2. Resolves inline $ref references
3. Generates synthetic test values for all parameters
4. Sends real HTTP requests to the server, sorted so list endpoints run before parameterized ones (e.g. GET /users before GET /users/{id}) — this lets the tool capture real IDs from responses and use them in subsequent requests
5. Classifies each response and writes the report

Limitations

• Only local $refs (#/components/...) are resolved; external file refs are not supported
• One auth config applies to all requests; per-endpoint auth is not supported
• Spec must be OpenAPI 3.x (not Swagger 2.x)