Skip to main content

OpenAPI Linting

Vague includes built-in OpenAPI linting powered by Spectral, helping you maintain high-quality API specifications.

Basic Usage​

Lint an OpenAPI spec:

vague --lint-spec openapi.json

Verbose Output​

Show all issues including hints:

vague --lint-spec openapi.yaml --lint-verbose

Output Format​

$ vague --lint-spec api.json

OpenAPI Linting Results
=======================

api.json
  3:10    error    oas3-api-servers     OpenAPI "servers" must be present and non-empty array.
  15:7    warning  operation-operationId    Operation must have "operationId".
  23:11   info     description-duplication  Property description duplicates summary.

✖ 3 problems (1 error, 1 warning, 1 info)

Severity Levels​

LevelDescription
errorMust fix — spec is invalid or has serious issues
warningShould fix — potential problems or bad practices
infoConsider fixing — suggestions for improvement
hintNice to have — minor suggestions (verbose only)

Common Rules​

Errors​

RuleDescription
oas3-schemaSpec must be valid OpenAPI 3.x
oas3-valid-schema-exampleExamples must match schema
path-paramsPath parameters must be defined

Warnings​

RuleDescription
operation-operationIdOperations should have IDs
operation-tagsOperations should have tags
operation-descriptionOperations should have descriptions
info-contactAPI should have contact info

Info​

RuleDescription
operation-success-responseShould define success responses
oas3-unused-componentUnused components detected

Programmatic API​

import { lintOpenAPISpec, SpectralLinter } from 'vague-lang';

// Simple function
const result = await lintOpenAPISpec('openapi.json');
console.log(result.errors);   // Error-level issues
console.log(result.warnings); // Warning-level issues
console.log(result.valid);    // true if no errors

// Class-based for multiple files
const linter = new SpectralLinter();
const result1 = await linter.lint('api1.json');
const result2 = await linter.lint('api2.yaml');

// Lint raw content
const result3 = await linter.lintContent(jsonString, 'json');

Integration Examples​

Pre-commit Hook​

#!/bin/bash
# .git/hooks/pre-commit

for spec in specs/*.json; do
  if ! vague --lint-spec "$spec"; then
    echo "Linting failed for $spec"
    exit 1
  fi
done

CI Pipeline​

# GitHub Actions
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install -g vague-lang
      - run: vague --lint-spec api.yaml

npm Script​

{
  "scripts": {
    "lint:api": "vague --lint-spec openapi.yaml",
    "lint:api:verbose": "vague --lint-spec openapi.yaml --lint-verbose"
  }
}

Workflow: Lint Before Generate​

#!/bin/bash
# Lint first, then generate if valid

if vague --lint-spec api.json; then
  echo "Spec is valid, generating data..."
  vague data.vague -v api.json -o output.json
else
  echo "Fix linting errors first"
  exit 1
fi

Fixing Common Issues​

Missing operationId​

# Before
paths:
  /pets:
    get:
      summary: List pets

# After
paths:
  /pets:
    get:
      operationId: listPets
      summary: List pets

Missing Servers​

# Before
openapi: 3.0.0
info:
  title: My API

# After
openapi: 3.0.0
info:
  title: My API
servers:
  - url: https://api.example.com

Invalid Example​

# Before - example doesn't match schema
schema:
  type: integer
example: "not a number"

# After
schema:
  type: integer
example: 42

See Also​