🚀 Why Lint and Validate Your API?

Validating your API is like spell-checking your OpenAPI file.
Linting is like code style enforcement for APIs.

✔ Catches missing fields, broken references, and syntax errors
✔ Ensures consistency across teams
✔ Prevents bad API design from making it to production
✔ Saves debugging time later

Now, let’s look at the tools that can help.

🛠 Tools for Linting and Validating OpenAPI

Let’s set up and use these tools.

🔍 1. Validate OpenAPI with Swagger Editor (Quick & Easy)

If you just need a quick syntax check, Swagger Editor is the easiest way.

1️⃣ Go to editor.swagger.io
2️⃣ Paste your OpenAPI YAML
3️⃣ Errors will automatically appear in real-time

🔹 Pros: Free, web-based, instant feedback
🔹 Cons: No custom rules, not ideal for large projects

🔥 2. Lint OpenAPI with Spectral (Best for CI/CD)

Spectral is the most powerful OpenAPI linting tool.
It enforces best practices and catches issues before deployment.

✅ Install Spectral:

1

npm install -g @stoplight/spectral

✅ Run Spectral on Your OpenAPI File:

1

spectral lint openapi.yaml

Example output:

1
2
3

openapi.yaml
  13:10  error  openapi-tags  OpenAPI object should have non-empty 'tags' array
  24:3   warning  operation-description  Operation must have a 'description' field

💡 Fix these issues before shipping your API!

🔧 3. Customize Spectral Rules (API Governance)

Spectral lets you define custom API linting rules in a .spectral.yaml file.

Example .spectral.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

extends: spectral:oas
rules:
  operation-description:
    description: "Every endpoint must have a description"
    severity: error
  info-contact:
    description: "APIs must include a contact email"
    severity: warning
    given: "$.info.contact"
    then:
      field: email
      function: truthy

Now, running spectral lint openapi.yaml will enforce your rules. 🚀

🔹 Pros: Highly customizable, great for teams
🔹 Cons: Requires setup

🏗 4. Validate OpenAPI with Redocly CLI

If you’re using ReDoc for API docs, use Redocly CLI to ensure compatibility.

✅ Install Redocly:

1

npm install -g @redocly/cli

✅ Validate OpenAPI:

1

redocly lint openapi.yaml

This checks:
✔ Schema structure
✔ Documentation completeness
✔ Redoc-specific optimizations

🔹 Pros: Ideal for ReDoc users
🔹 Cons: Focused on API documentation, not API behavior

🔄 5. Automate Linting in CI/CD

Want every API change to be checked automatically?
Add Spectral to your CI/CD pipeline.

GitHub Actions Example:

Create .github/workflows/openapi-lint.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

name: Lint OpenAPI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Spectral
        run: npm install -g @stoplight/spectral
      - name: Lint OpenAPI
        run: spectral lint openapi.yaml

Now, every pull request will be automatically checked for OpenAPI errors. 🚀

❌ Common OpenAPI Mistakes (and How to Fix Them)