Bring everything you have. Leave with more than you came with.
The collections of the client you use today come across with their auth, scripts, variables and tests. A specification — OpenAPI, Swagger, WSDL, OData, FHIR — becomes a project and stays attached to it, so every answer can be read against it and a newer spec updates the project without touching your edits. And a project writes its own documentation: an HTML file, or OpenAPI 3.1, 3.0 or Swagger 2.0.
What imports
The spec comes in once. It stays attached.
In most clients an import is a one-way door: the spec becomes a folder of requests and is forgotten. In Sonda a request remembers which operation of the spec it came from, and that link is what makes the rest possible — a Spec tab on the request that says what the operation expects, a real answer read against the spec with its drift named, and a newer spec that updates the project without touching anything you changed.
What goes out is written from the project as it stands: one self-contained HTML file, or an OpenAPI 3.1, 3.0 or Swagger 2.0 document — with the code samples, the examples and the checks, and never an auth value.
The request and answer panesThree things a forgotten spec cannot do.
A request remembers which operation it came from. Everything on this page follows from that.
What the operation expects, on the request.
A Spec tab on the request: the parameters, the body schema, and whether the body you have was edited away from it. Not a document in another window — the operation, beside the request that calls it.
Drift: the answer read against the spec.
A real answer, read against what the spec promised: a status it does not document, fields it does not list, headers it promised that did not come, a content type that differs. Each named on the answer, not as a red light. It is also a check — "the answer matches the spec" — so a runner, a flow or a schedule fails the moment the API and its document part ways.
Update from a newer spec. Nothing is deleted.
From a file or by fetching the URL again. What the spec owns is updated; the person's edits are kept; new operations are added; removed ones move to a "Removed from the spec" folder, where they stay until you decide. A spec that changes every sprint is a spec you can keep following.
The document said one thing. The API did another.
Drift is not a report you run on Fridays. It is read on every answer that comes back to a request with a spec behind it, and it is a check like any other — put it on the requests that matter and the runner, the flow and the schedule will tell you when the two part ways.
Beside it, one answer from a customers endpoint and what the spec had to say about it: a field the schema never heard of, a header that was promised and did not come. The status and the content type were fine, so they say so.
Exports, documentation and code samples.
Auth values are never written out. A variable whose name looks like a secret stays as its name.