DocSemantic: catching API spec drift in CI before your customers do

Ali Duale — Tue, 29 Sep 2026 15:31:09 +0000

I come from a social services background—not a developer by training. I just read a lot and get curious.

The first time I heard the word "drift" was when my insurance company sent me an invoice with wrong items and wrong total. Support admitted it was a drift error—their systems had just been updated. I thought: why did it reach me at all? A drift check before sending the invoice would have caught it.

Later, a phone repair guy used the same word for a different problem. Two industries, same concept: two things meant to stay in sync slowly drifting apart. Nobody decides to break it. It just happens.

In software, the clearest example is your API spec vs. your live API. The spec says a field is a number. Somewhere along the way, the API starts returning a string. Nothing crashes. Tests pass. But the contract is now a lie—and nobody knows until something downstream breaks.

I read everything I could find about this, saw the gaps in static spec linters, and spent the last seven months building DocSemantic.

What it does

It compares your OpenAPI or Postman spec against what your API actually does. We learn a baseline from real traffic. When the spec and the live API disagree, you find out in CI—not from a customer email.

The GitHub Action is a thin client: one authenticated POST, pass or fail.


yaml
name: API Contract Check
on: [push, pull_request]

jobs:
  spec-check:
    runs-on: ubuntu-latest
    steps:
      - name: DocSemantic Spec Check
        uses: LingodocApi/docsemantic-action-check-spec@v1
        with:
          api-key: ${{ secrets.DOCSEMANTIC_API_KEY }}

DEV Community: Ali Duale

DocSemantic: catching API spec drift in CI before your customers do

What it does