Migrating from Optic to DocSemantic

Everything Optic used still applies. Find your optic.yml (usually at the repo root) and the OpenAPI/Swagger files it points to. The OpenAPI files are what matter — DocSemantic uses them as your contract unchanged. A typical config looks like this:

# optic.yml — a typical Optic v0.50+ project config
files:
  - path: ./openapi.yml
    id: orders-api

capture:
  openapi.yml:
    server:
      command: npm start
      url: http://localhost:8080
    requests:
      run:
        command: npm test

From this file, DocSemantic picks up the API name under capture. The openapi.yml it refers to is what we check traffic against, so you'll paste or upload that file in the next step.

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 together with the OpenAPI file it references. We can't fetch paths from your repo, so the spec itself has to be pasted or uploaded. Each spec becomes a contract. Then point CI at it with the GitHub Action below.

Replace the Optic diff step with the DocSemantic Spec Check Action. Store your key as a repo secret named DOCSEMANTIC_API_KEY. The step fails when the hosted check reports drift, so it can still block merges, but it checks something different from optic diff (see what's different).

# .github/workflows/api.yml  —  BEFORE (Optic)
name: API checks
on: [push, pull_request]
jobs:
  optic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npx @useoptic/optic diff openapi.yml --base main --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:
      # fails the step when the hosted check reports drift
      # (set fail-on-drift: "false" to report without failing)
      - uses: LingodocApi/docsemantic-action-check-spec@v1
        with:
          api-key: ${{ secrets.DOCSEMANTIC_API_KEY }}

Once your contracts are in, these are available if you want them:

• Plain-English AI explanations of drift (counts toward your plan's AI generations).
• Spec-update pull requests for drift you decide is intentional — always opened for review, never merged automatically.
• Consumer tracking that shows which caller sent the request whose response drifted.
• Scheduled checks on production traffic, so drift shows up outside CI too.