OpenAPI Validation — Ensuring Spec Accuracy and Compliance

In this tutorial, you will learn about OpenAPI Validation. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI validation ensures your specification is syntactically correct, follows style guidelines, and does not introduce breaking changes. Automated validation is essential for maintaining spec quality.

What You'll Learn

You will learn how to validate OpenAPI specs for syntax, schema Compliance, style rules, and breaking changes, and how to integrate validation into CI/CD.

Validation Types

# Syntax validation
npx swagger-cli validate openapi.yaml

# Style validation with Spectral
npx @stoplight/spectral-cli lint openapi.yaml

# Breaking change detection
npx @stoplight/diff-cli diff \
  --base origin/main:openapi.yaml \
  --head HEAD:openapi.yaml

CI/CD Validation

name: Validate OpenAPI
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Spectral lint
        run: npx @stoplight/spectral-cli lint openapi.yaml
      - name: Check breaking changes
        run: |
          npx @stoplight/diff-cli diff \
            --base origin/main:openapi.yaml \
            --head HEAD:openapi.yaml

Custom Spectral Rules

rules:
  operation-summary:
    description: Operations must have summaries
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: summary
      function: truthy

Common Mistakes

1. No validation at all — Deploying specs without validation.
2. Only syntax validation — Not checking style or breaking changes.
3. Ignoring warnings — Treating warnings as acceptable.

Practice Questions

1. What types of validation should you run?
2. How do you detect breaking changes?
3. How do you create custom Spectral rules?
4. How do you integrate validation into CI?

Challenge

Create a complete validation pipeline that checks syntax, style with 10 custom Spectral rules, breaking changes against the main branch, and generates a validation report.

What's Next

In the final lesson, you will complete an OpenAPI project.