Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 37 ยท Projects and Practice

Project: A Spec Quality Gate for CI

Build a continuous-integration quality gate for an OpenAPI repository that lints, detects breaking changes, builds docs and generates an SDK, with a runnable gate-logic stand-in.

This project turns the earlier lessons into one automated pipeline: every pull request that touches the OpenAPI document is linted, compared for breaking changes, bundled, turned into documentation and used to generate an SDK. If any step fails, the merge is blocked. The result is a repository where the contract can never silently rot.

The real tools (Spectral, oasdiff, Redocly CLI, OpenAPI Generator) cannot run on this website, so the pipeline file is read-only. A Python stand-in implements the gate logic, the part that decides pass or fail, so that you can try the rules.

The repository layout

TEXT
bookstore-api/
  api/
    openapi.yaml
    paths/ schemas/ responses/
  .spectral.yaml
  .openapi-generator-ignore
  generator-config.yaml
  .github/workflows/api.yml

The pipeline

flowchart LR
  A["Pull request"] --> B["Lint<br/>Spectral"]
  B --> C["Bundle<br/>redocly bundle"]
  C --> D["Breaking-change diff<br/>oasdiff vs main"]
  D --> E["Build docs"]
  E --> F["Generate SDK<br/>and compile it"]
  F --> G["Mock + contract tests"]
  G --> H["Merge allowed"]

Each stage can fail the build; the order puts cheap checks first.

A GitHub Actions workflow for it (read-only):

YAML
name: api
on:
  pull_request:
    paths: ["api/**", ".spectral.yaml"]

jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: {fetch-depth: 0}
      - uses: actions/setup-node@v4
        with: {node-version: 22}

      - name: Lint
        run: npx --yes @stoplight/spectral-cli lint api/openapi.yaml --fail-severity warn

      - name: Bundle
        run: npx --yes @redocly/cli bundle api/openapi.yaml --output dist/openapi.yaml

      - name: Breaking changes against main
        run: |
          git show origin/main:api/openapi.yaml > /tmp/base.yaml || true
          npx --yes @redocly/cli bundle /tmp/base.yaml --output /tmp/base.bundled.yaml
          oasdiff breaking /tmp/base.bundled.yaml dist/openapi.yaml --fail-on ERR

      - name: Build docs
        run: npx --yes @redocly/cli build-docs dist/openapi.yaml --output dist/docs.html

      - name: Generate and compile the TypeScript SDK
        run: |
          npx --yes @openapitools/openapi-generator-cli generate \
            -i dist/openapi.yaml -g typescript-fetch -o dist/sdk-ts -c generator-config.yaml
          cd dist/sdk-ts && npm install && npm run build

      - uses: actions/upload-artifact@v4
        with: {name: api-docs, path: dist/}

(Real projects pin exact tool versions rather than using floating npx versions, and install oasdiff from a release or a container.)

The gate logic

The most interesting part is the decision: which findings block the merge? A good gate follows three rules.

  1. Lint errors always block; warnings block only when the file is new or the team has opted in.
  2. Breaking changes block unless the major version changed and the pull request carries an approval label.
  3. Missing docs coverage (operations without a summary) blocks above a threshold.

The stand-in takes a report from each stage and applies these rules, printing a verdict and a non-zero exit status as CI would.

Python Stand-in: gate decision for a pull request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Make it pleasant to use

  • Cache Node and Java downloads so the job runs in a minute or two.
  • Post a comment on the pull request with the oasdiff changelog, so reviewers see a readable list of changes.
  • Preview docs by uploading the built HTML as an artifact or to a temporary URL.
  • On merge to main, publish the docs, tag the spec version, and publish SDKs (client SDK lesson).
  • Document an escape hatch: a label such as breaking-approved that a lead can set, so that emergencies are not blocked but are visible.

Stretch goals

  • Run the Prism mock in the pipeline and let your front-end tests call it.
  • Add a nightly job that runs contract tests against the staging API.
  • Fail the build when the generated SDK is not committed, if you keep SDK sources in the repo (a drift check).

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why does the pipeline run linting before generating the SDK?

    Ordering from cheap to expensive saves time and gives early, clear feedback.
  2. 2. When should a breaking change be allowed to merge in this gate?

    A version bump plus explicit approval makes the break deliberate and visible.
  3. 3. Which artifact should the SDK generator and docs builder read?

    The bundled document is complete and self-contained, so every tool sees the same input.

Summary

  • A quality gate chains lint, bundle, breaking-change diff, docs and SDK generation in CI.
  • Decide up front which findings block a merge and provide a visible override.
  • Cache tools, comment diffs on the pull request and publish artifacts.
  • Pin tool versions so the pipeline is reproducible.
  • The Python gate is a stand-in for the decision logic; the YAML is a read-only template.

Next: Project: a contract test suite