01 Contract-aware documentation

Catch the example
your schema left behind.

Lint the JSON and curl snippets humans actually copy. One small CI gate connects Markdown, OpenAPI, and clear line-level fixes.

cargo install --git github.com/…/sf-api-example-linter

Shell-safe curl is parsed, never run

Offline-first remote refs stay off

CI-native precise annotations

02 The shortest path to trustworthy docs

Examples enter the contract.

No fixture migration. Point the linter at the documentation you already maintain and choose the operation or schema that gives each block meaning.

01
Extract
Find fenced JSON and curl bodies in Markdown, plus examples embedded in OpenAPI 3.x.
docs/**/*.md
02
Align
Resolve the operation or named schema, including local references and request/response direction.
operation=createPet
03
Explain
Return the file, line, JSON pointer, and exact mismatch in text, JSON, or GitHub format.
$/tag · not allowed

03 Recorded run

This recording uses the real CLI output contract. Nothing is uploaded, and playback begins only when you ask.

docs/create-pet.md

Ready to lint 2 examples.

Recording stopped at the first frame.

04 Small surface, useful coverage

Validate literal request and response payloads, with optional metadata right on the fence.

Extract JSON data flags as text. Never invoke a shell, source an environment, or follow a redirect.

Check media examples already inside 3.0 and 3.1 documents against their own operation schema.

05 Five-minute setup

Add one config file and one CI command. When a field drifts, the pull request points to the example that needs repair.

.api-example-linter.json

{
  "spec": "openapi.yaml",
  "inputs": ["docs"],
  "operation": "createPet",
  "direction": "request"
}

api-example-linter check --format github