Spec source

A spec source is an OpenAPI document — a URL or a file — that Tinspec keeps reading. Endpoints are generated from it. In the app these are surfaced as API providers.

What “live binding” means

Importing a spec copies it once. Binding keeps reading it.

Tinspec re-resolves the document on an interval you configure per provider. Each resolve produces the current endpoint set, so:

• an operation added to the spec appears;
• one removed from the spec disappears;
• one whose parameters, body, or responses changed updates in place.

You are never testing against last quarter’s snapshot. When the service is unreachable, the last successfully fetched document is served from the local cache, so the endpoints stay usable offline.

This is the difference that matters for a generated spec: your framework emits a new /v3/api-docs on every deploy, and the endpoint list simply follows it.

Changes are reviewed, not silent

A live binding that silently rewrote things under you would be worse than a snapshot. So every difference lands in the Spec Changes view, which keeps a per-endpoint snapshot of what it last showed you and diffs against it field by field.

A modified endpoint expands to show exactly what moved. A removed endpoint keeps its last-known shape so you can still read what it used to be.

Acknowledging is always an explicit act — a per-row tick, Mark seen for one provider, or Mark all seen. Opening an endpoint to inspect it does not acknowledge anything.

From the same view you can tick endpoints and copy a minimal, valid OpenAPI subset of just those operations — with path-level parameters, every transitively referenced schema, and the security schemes, and nothing else. Useful for a ticket, a code review, or handing an agent exactly the part of the API under discussion. Removed endpoints can be reconstructed into the subset from their last-seen snapshot.

Reconciling generated endpoints with your edits

The tension in a live binding: the endpoint is regenerated every poll, but you tweaked it.

Tinspec resolves this with overlays. When you edit a generated endpoint’s body, params, headers, auth, gRPC message, GraphQL document, pre-run chain, or gateway binding, it diffs your version against a pristine clone and records only the field groups that differ, as committable YAML in .tinspec/overlays/<provider-id>.yaml. Every fresh resolve re-applies them.

Rules worth knowing:

• An overlaid group replaces the generated one wholesale — it is not a field-level merge.
• URL and method are not overlayable. They form the endpoint’s identity, which is also the key for overlays, the change baseline, and tab state.
• When a poll changes an endpoint underneath an existing edit, the editor shows an amber banner offering Keep edits or Reset to spec. It will not choose for you.

An edited endpoint carries an Edited chip in the editor and a dot in the navigator, and offers Reset to spec at any time.

In the file format

A spec source in a collection is three fields — a name, a location, and an optional route matcher binding:

specSources:
  - name: Users API
    location: http://localhost:8080/openapi.json
    routeMatcher:
      matcher: edge-kong
      upstream: users-service
      gatewayUrl: "{{gatewayUrl}}"

In a project with a folder, API providers are also written one YAML file per provider under .tinspec/providers/.