Bind your first API spec
An API provider is a live binding to an OpenAPI document. Adding one is how endpoints get into Tinspec — you do not import and then maintain a copy.
Add the provider
Section titled “Add the provider”From the navigator’s API providers section, add a source and give it the location of your OpenAPI document. Either works:
- A URL —
http://localhost:8080/v3/api-docsfor springdoc,/openapi.jsonfor FastAPI, or any URL that serves the document. - A file — a
.jsonor.yamlspec on disk.
Tinspec fetches the document, resolves it, and the endpoints appear in the navigator grouped by their OpenAPI tags.
If you don’t know the path
Section titled “If you don’t know the path”Give Tinspec the base URL of the service and let it discover the spec. It probes the
well-known documentation locations — /openapi.json, /v3/api-docs, /swagger.json and the
like — and offers what it finds.
This probes documentation endpoints only. It never guesses at resource paths, so it will not send traffic at your actual API looking for something that responds.
What you get
Section titled “What you get”Each endpoint is a ready-to-send request: method, URL, path and query parameters typed from the spec, headers, and a generated example body built from the request schema. Open one and the Docs view shows its parameters, body fields, and documented response codes.
The binding is live
Section titled “The binding is live”Tinspec polls the document on an interval you set per provider. When the spec moves:
- new operations appear,
- removed ones disappear,
- changed ones update in place.
If the service goes offline, the last successfully fetched document is cached, so your endpoints keep working.
Changes are not silent. The Spec Changes view collects everything that moved since you last looked and explains each modified endpoint field by field — a parameter that became required, a response that changed shape, a body field that vanished. Acknowledging a change is always explicit: tick the row, or use Mark seen per provider. Opening an endpoint to look at it does not mark it as reviewed.
Your edits are not clobbered
Section titled “Your edits are not clobbered”A spec-generated endpoint is regenerated on every poll, but edits you make to one persist.
Change its body, params, headers, or auth in Form view and Tinspec records an overlay — the
field groups that differ from the generated request — as committable YAML in
.tinspec/overlays/. The overlay is re-applied after every refresh.
The editor marks such an endpoint with an Edited chip and offers Reset to spec. If the spec changes underneath an edit you made, you get an amber banner with two choices — Keep edits or Reset to spec. Nothing is ever merged silently.
URL and method are deliberately not overlayable: they are the endpoint’s identity.