OutworxOutworx Docs
Spec Diff · Pro and Business

Catch breaking changes before reviewers approve.

Compare any two project versions and Outworx classifies every change as breaking, additive, or cosmetic — then suggests a semver bump. Drop the GitHub Action into .github/workflows/ and every spec PR gets a review comment with the diff before reviewers see it.

Pro and BusinessReplaces: Bump.sh · openapi-diff · oasdiff
Wire up the actionGitHub Actions guide
github.com/acme/api · PR #482
🤖
outworx-docscommented just now

Suggested bump: major — 2 breaking, 1 additive, 1 cosmetic

⚠️ Breaking changes

  • DELETE /v1/users/{id}/sessions — endpoint removed
  • User.email — now required (was optional)

✨ Additive changes

  • POST /v1/users/{id}/invites — new endpoint

📝 Cosmetic changes

  • listUsers — description updated

Classification engine

Every change lands in one of three buckets.

Deterministic ruleset — no LLM-flavored interpretation. Same spec in, same classification out. The PR comment, the semver suggestion, and the dashboard's interactive diff all read from the same engine.

Breaking

severity

Removing a required field, narrowing an enum, deleting an endpoint, tightening a regex `pattern`, switching a status code from 200 to 204.

  • DELETE /v1/users/{id}/sessions — endpoint removed
  • User.email — was optional, now required
  • Status — 200 → 204 (no body)

Additive

severity

New optional fields, new endpoints, new examples, widened enums. Safe to release as a minor bump.

  • POST /v1/users/{id}/invites — new endpoint
  • User.preferences — new optional field
  • WebhookEvent — added two new variants

Cosmetic

severity

Description tweaks, summary updates, tag re-assignments, example body changes that don't affect the schema. Patch-bump material.

  • listUsers — description updated
  • AuthScheme — tag added
  • checkout — example body refined
Semver suggestion logic: any breaking → major, otherwise any additive → minor, otherwise patch. Reviewers can override in the merge commit; the default catches the careless cases.

GitHub Action

One workflow file. Sticky review comment on every PR.

Drop the file into .github/workflows/spec-diff.yml. Add OUTWORX_TOKEN to repo secrets. Done. The action POSTs the head + base spec to the diff endpoint, then sticky-comments the rendered markdown on the PR — subsequent pushes update the same comment in place rather than spamming new ones.

.github/workflows/spec-diff.yml
# Drop into your repo as-is. Add OUTWORX_TOKEN to secrets.

name: Spec Diff
on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'openapi.yml'
      - 'openapi.json'

jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: outworx/spec-diff-action@v1
        with:
          slug: acme
          token: ${{ secrets.OUTWORX_TOKEN }}
1

PR opens

The action triggers on any pull_request event that touches openapi.yaml / openapi.yml / openapi.json (configurable).

2

Diff is computed

The action POSTs both specs to docs.outworx.io/api/projects/<slug>/diff. Cross-format guard allows OpenAPI ↔ Swagger, refuses GraphQL ↔ HTTP.

3

Comment is posted

Bold semver bump suggestion + grouped sections (Breaking / Additive / Cosmetic) with bullet lists. Pure markdown — GitHub renders it natively.

4

Subsequent pushes

Sticky comment updates in place using a hidden marker line. No comment spam, no notification storms.

Rate limit: 60 diffs/min/project (same Upstash limiter as MCP). A runaway CI loop fails open with a 429 — your PR comment shows the throttle, then retries automatically next push.

Compare versions
Before
v1.4.0 (default)
After
v2.0.0
Suggested bumpmajor2 breaking · 1 additive · 1 cosmetic
Breaking changes
  • DELETE /v1/users/{id}/sessions — endpoint removed
  • User.email — now required
Additive changes
  • POST /v1/users/{id}/invites — new endpoint

Dashboard interactive diff

Compare any two versions, any time.

Picking versions for a migration guide? Pre-flighting a cut? The dashboard's Diff tab uses the same classification engine the GitHub Action uses, but with rich UI: colored severity badges, expandable change details, and one-click export of the migration guide outline.

  • Pre-selects the two newest versions — owners usually want “what changed in the latest upload” first.
  • Format mismatch warning — GraphQL ↔ HTTP gets a friendly explainer instead of a confusing diff. OpenAPI ↔ Swagger comparisons fire cleanly (useful for migrations).
  • Same engine, same numbers. The PR comment and the dashboard never disagree — they read from one source.

Plan tiers

Spec diff ships on every paid plan.

Free

—

  • Try-It playground
  • No spec-diff API access
  • No GitHub Action token
Most popular

Pro

60 / min / project

  • Diff API at /api/projects/<slug>/diff
  • GitHub Action workflow file
  • Sticky PR comments
  • Dashboard interactive diff
  • Cross-format guard (OpenAPI ↔ Swagger)

Business

60 / min / project

  • Everything in Pro
  • Custom domain on the docs
  • Priority support
  • SLA on the diff API

Pairs well with

SDK Generator

Pair with single-file SDK regeneration on merge — the action posts the diff, the SDK regenerates only after the PR ships.

Docs page builder

Use the diff classification to seed a migration guide section. Add a markdown intro under the affected endpoints.

Uptime monitoring

When the diff flags a removed endpoint, monitoring auto-stops probing it. No alarms on operations you intentionally killed.

The PR comment your reviewers wish they had.

Pro plan unlocks the diff API, the GitHub Action, and the dashboard's interactive diff. $9/month flat.

Start freeCompare plans