Skip to content
You are reading the v2 docs, currently in beta.V1 docs
oRPC
Esc
↑↓navigate↵open⌘Jpreview
On this page

Detecting Breaking Changes

Learn how to detect breaking API changes before they reach your clients, by comparing the OpenAPI documents of any oRPC project with oasdiff in CI.

Catch changes that break existing clients, such as a new required input or a removed output field, by comparing OpenAPI documents with oasdiff.

Generate the Document

Write the OpenAPI document of your router to a file, and commit it to your main branch. The comparison needs it there as a baseline.

import { writeFile } from 'node:fs/promises'

import { OpenAPIGenerator } from '@orpc/openapi'
import { ZodToJsonSchemaConverter } from '@orpc/zod'

const generator = new OpenAPIGenerator({
  converters: [new ZodToJsonSchemaConverter()],
})

const spec = await generator.generate(router)

await writeFile('openapi.json', `${JSON.stringify(spec, null, 2)}\n`)

Compare

Install oasdiff, then regenerate the document and compare it with the one on your main branch:

node scripts/openapi.ts
oasdiff breaking --fail-on WARN origin/main:openapi.json openapi.json

The oasdiff command exits with a non-zero code when it finds a breaking change.

Run in CI

This workflow regenerates openapi.json, commits it to the pull request, and compares it with the base branch using the oasdiff GitHub Action:

name: oasdiff

on:
  pull_request:
    branches: ['main']

permissions:
  contents: write # lets the workflow commit the generated document
  pull-requests: write # lets the action post the changes as a PR comment

jobs:
  breaking-changes:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.head_ref }}

      - run: git fetch --depth=1 origin ${{ github.base_ref }}

      - uses: pnpm/action-setup@v6

      - run: pnpm i

      - run: node scripts/openapi.ts

      - uses: stefanzweifel/git-auto-commit-action@v7
        with:
          commit_message: 'chore: update openapi.json'
          file_pattern: openapi.json

      - uses: oasdiff/oasdiff-action/breaking@v0
        with:
          base: 'origin/${{ github.base_ref }}:openapi.json'
          revision: 'openapi.json'
          fail-on: WARN

Last updated on

Was this page helpful?