Inso CLI in CI: lint and export a Sume OpenAPI copy in Insomnia

The answer

Kong's Insomnia import and export reference says that in CI you can run inso lint spec <identifier> to lint OpenAPI and fail builds on errors, and inso export spec to extract the raw spec tied to an API collection, printing to stdout when you omit --output. That gives you a cheap gate for a vendored copy of Sume's OpenAPI.

It will tell you the document is well formed. It will not tell you Sume's behaviour matches the document; for that you need a contract test against real responses.

What each command does

The reference describes the commands as a way to supplement the app with command-line work: running tests, executing collections, validating specs and exporting OpenAPI artifacts.

A workable CI shape

Import the Sume spec into an Insomnia API collection once, commit the exported collection or the spec file, and let CI run the lint. When you refresh the spec from https://api.sume.com/reference/json, the lint runs on the new copy before anyone merges it.

Keep the lint and the live check separate. The lint catches a corrupted download or a bad merge. A small scheduled request that reads a status endpoint with a read-only key catches an API that has drifted from your copy.

Spec details worth knowing before you lint

Sume's document is OpenAPI 3.0.3 and uses nullable: true on fields such as next_poll_after_seconds. A linter configured for 3.1 rules may complain about that style, so set expectations by version. The same document declares an Idempotency-Key header parameter on create operations, which your generated clients should expose.

What to do on failure

If the lint fails on a fresh download, do not edit the vendored file by hand. Keep the last good copy, open a note with the failing rule, and re-download later. A hand-edited spec silently diverges from the server and defeats the point of having one.

Pairing the lint with a contract probe

A lint answers whether the file is a valid spec. A probe answers whether the server still matches it. Run a single read-only request on a schedule, parse the status or list response, and compare field names against your copy. When a field is added, that is fine; when a field you rely on disappears or changes type, fail the job and look at the diff of the new download.

Keep the probe cheap. A list or a status read costs nothing, so it is safe to run daily, and it never creates a paid job. Avoid probing with a create call, because even with an Idempotency-Key it is a paid operation.