Migrating from Optic to DocSemantic

Everything Optic used still applies. Find your optic.yml (usually at the repo root) and any OpenAPI/Swagger documents it referenced. You don't need to convert or rewrite anything — DocSemantic reads these formats directly.

No spec on hand? That's fine too — DocSemantic can learn your contract from live traffic, so you can skip straight to sending samples.

Sign up, then open Import from Optic and paste your optic.yml. We discover the specs it points to and register each API as a contract. Prefer the terminal? The CLI does the same thing:

# 1. Get the CLI (zero-dependency, not on npm yet — run it from a clone)
git clone https://github.com/LingodocApi/docsemantic.git
cd docsemantic
alias docsemantic="node $PWD/cli/bin/docsemantic.js"

# 2. Point it at your workspace (grab a key from Settings → API keys)
docsemantic init --url "$DOCSEMANTIC_URL" --key "$DOCSEMANTIC_KEY"

# 3. Verify it can see your contract
docsemantic report

This is the only change to your pipeline. Replace the Optic diff step with docsemantic check. It exits non-zero when a breaking change is detected, so it blocks PRs exactly like Optic did — no other workflow changes needed.

# .github/workflows/api.yml  —  BEFORE (Optic)
name: API checks
on: [push, pull_request]
jobs:
  optic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @useoptic/optic diff --check   # ← no longer maintained

# .github/workflows/api-drift.yml  —  AFTER (DocSemantic)
name: API drift
on: [push, pull_request]
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      # exits non-zero when drift is detected → fails the job, same as before
      - uses: LingodocApi/docsemantic/github-action@main
        with:
          api-key: ${{ secrets.DOCSEMANTIC_KEY }}

Once your contracts are in, you get the parts Optic never had — all optional, all off by default:

• Plain-English AI explanations of every drift, so reviewers understand the impact without reading a diff.
• Auto-fix pull requests that update the spec (or flag the code) when drift is intentional.
• Consumer tracking that names which frontend or service actually breaks — not just that something changed.
• Continuous production monitoring, so drift is caught from real traffic, not only in CI.