feat(api): add api spec <spec> command

[gu-stav]

Description

Adds sanity api spec <slug> for inspecting one OpenAPI spec.

• Default: structured human view — header + per-operation blocks (method, endpoint, operationId, capability tags, summary, typed params, request body, responses, auth, "Schemas referenced" footer).
• --format=json — per-operation JSON envelope, agent-friendly.
• --format=openapi — raw YAML, byte-for-byte passthrough of the upstream spec.
• --operation=<id> — narrow any output mode to a single operation.
• --schema <name> — print one components.schemas.<name> entry (follows $ref pointers from operation output). Honors --format (default YAML).
• --web — open the docs page in a browser.

Deprecates sanity openapi get (passthrough output preserved during the back-compat window).

This PR is the second in a stack:

• feat(api): add api list command and deprecate openapi * #1070 — sanity api list
• feat(api): add api spec <spec> command #1073 (this PR) — sanity api spec <slug>
• feat(api): add sanity api <endpoint> command #1074 — sanity api <endpoint> (default)

Architecture refactors (post-review)

• $ref policy: link, never resolve. Body/response schemas carry ref: '<schemaName>'; agents follow up with --schema <name>.
• Drop OperationJsonView pass-through projection — buildSpecJsonView now uses ParsedOperation directly (~30 lines + one type gone).
• Use shared docsUrlFor() + loadSingleSpecOrThrow() helpers from list-branch refactor; drop local HTTP_REFERENCE_BASE_URL and the bespoke loadSpec private method.

PR review items addressed

• Reject --operation + --format=openapi upfront (typo'd op no longer silently produces full raw YAML).
• Debug-log when extractRequestBody skips a body-level $ref (the operation would otherwise render as bodyless without trace).
• Gate "Query params (required)" behind a length check — optional-only operations no longer render a dead (none) block.

What to review

• packages/@sanity/cli/src/commands/api/spec.ts — the new command.
• packages/@sanity/cli/src/api/parser.ts + extractors.ts + internal.ts — the rich OpenAPI parser introduced for this PR.
• packages/@sanity/cli/src/api/views.ts — list view + spec view, both human and JSON.
• packages/@sanity/cli/src/commands/openapi/get.ts — deprecation forwarder.

Testing

15 unit tests in commands/api/__tests__/spec.test.ts covering: human view, JSON envelope, OpenAPI YAML passthrough, --operation narrow + unknown-op error, --schema YAML default + JSON + unknown-schema error, --operation + --format=openapi conflict, optional-only query gating, --web flow, unknown slug, docs service unreachable. Plus 33 parser tests.

[claude]

Claude finished @gu-stav's task in 3m 15s —— View job

---

Review

The Cursor Bugbot finding (--operation silently ignored with --format=openapi) is already fixed in f1e517f — spec.ts:86-92 rejects the combo upfront. Bugbot was reviewing the older commit e28984b4. No action needed.

A small set of issues worth addressing below; nothing blocking.

---

1. Changeset includes an internal rename that never reached users

File: .changeset/add-api-spec-command.md

The per-operation JSON renames path to openApiPath to disambiguate it from the callable endpoint.

This rename happened during PR review of an unreleased command (commit f9a9ed8). Since sanity api spec is brand new in this changeset, there is no path → openApiPath rename for users — the field is just openApiPath from day one. The sentence describes internals and inflates the entry. Also: per the product-copy guidance, the summary is long and packs multiple changes into one paragraph.

Suggested tighter copy:

Adds `sanity api spec <slug>` for inspecting one OpenAPI spec. Default
output is a structured per-operation view; `--format=json` emits a JSON
envelope, `--format=openapi` passes through the raw YAML, `--operation`
narrows to one operation, and `--schema <name>` prints one component
schema. Deprecates `sanity openapi get` (output preserved during the
back-compat window).

Fix this →

---

2. --format=yaml without --schema silently produces the human view

File: packages/@sanity/cli/src/commands/api/spec.ts:53-59, 144

--format=yaml is only meaningful with --schema. Without it, the code falls through to renderSpecHumanView — neither YAML nor an error. The flag description does call this out ("paired with --schema; no effect otherwise"), but this is exactly the class of silent-no-op that the other upfront guards (lines 86, 98, 109) were added to prevent. The user gets identical output to omitting the flag, with no signal that they typed something meaningless.

Suggested: reject the combo upfront, matching the other guards:

if (flags.format === 'yaml' && !flags.schema) {
  this.error(
    '`--format=yaml` only applies with `--schema`. Drop `--format` or add `--schema <name>`.',
    {exit: 1},
  )
}

Tests in spec.test.ts don't cover this case today either way.

Fix this →

---

3. --web silently ignores other flags

File: packages/@sanity/cli/src/commands/api/spec.ts:76-81

sanity api spec jobs --web --operation=foo opens the docs page and silently drops --operation. Same with --schema, --format=openapi, etc. The PR adds upfront guards for other silent-ignore footguns (--format=openapi + --operation, --schema + --operation) but not for --web. Low-stakes since --web is interactive, but reads inconsistent next to the other guards.

Optional: reject --web combined with any of --operation, --schema, --format. Or document the precedence explicitly in the flag description.

---

4. Composition flattening only runs at the body root

File: packages/@sanity/cli/src/api/extractors.ts:206-247

walkProperty / walkProperties handle nested objects but do not call flattenComposition on them. So a request body of the shape:

properties:
  payload:
    allOf:
      - { properties: { a: { type: string } } }
      - { properties: { b: { type: string } } }

renders payload with empty fields and no refs surfaced. The root-level body handles this correctly via flattenComposition, but nested composition is missed. None of Sanity's current specs may hit this, but worth a debug log or a follow-up note in the doc-comment so the gap is auditable later.

---

5. extractResponses drops response-level $refs entirely

File: packages/@sanity/cli/src/api/extractors.ts:386

if (asString(response.$ref)) continue

The comment explains: "uncommon in our specs, and the schema lookup covers the use case if anyone needs it." But the row is silently dropped without a debug log, unlike the body-level $ref skip (lines 326-330) which does log. Consider symmetry — add a debug(...) so the same observability applies when a spec starts using this pattern.

---

6. Coverage: extractors.ts at 82.7%

The new extractor module is the lowest-covered new file. From a quick scan, the uncovered branches likely include the response $ref skip (point 5 above), the body-level $ref skip path, and parts of flattenComposition's oneOf/anyOf fork. None are user-facing critical, but worth a follow-up if you want full coverage parity with parser.ts (94.8%) and spec.ts (100%).

---

Summary

• Read the PR diff against base branch
• Review commands/api/spec.ts
• Review api/parser.ts + extractors.ts
• Review api/views.ts
• Review commands/openapi/get.ts deprecation
• Check tests and changeset
• Post final review

The architecture is solid — link-not-resolve $ref policy is well-motivated and consistently applied, the conflict guards added in f1e517f close the main silent-ignore footguns, and the parse/fetch error split in loadSingleSpecOrThrow cleanly distinguishes "spec is bad" from "service is unavailable." Items above are tightening, not redirecting.
· Branch

[github-actions]

📦 Bundle Stats — @sanity/cli

Compared against feat/api-command-list (309e558a)

@sanity/cli

Metric	Value	vs feat/api-command-list (309e558)
Internal (raw)	2.1 KB	-
Internal (gzip)	799 B	-
Bundled (raw)	10.97 MB	-
Bundled (gzip)	2.06 MB	-
Import time	869ms	+12ms, +1.4%

bin:sanity

Metric	Value	vs feat/api-command-list (309e558)
Internal (raw)	975 B	-
Internal (gzip)	460 B	-
Bundled (raw)	9.84 MB	-
Bundled (gzip)	1.77 MB	-
Import time	976ms	+10ms, +1.0%

🗺️ View treemap · Artifacts

Details

• Import time regressions over 10% are flagged with ⚠️
• Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.

📦 Bundle Stats — @sanity/cli-core

Compared against feat/api-command-list (309e558a)

Metric	Value	vs feat/api-command-list (309e558)
Internal (raw)	95.5 KB	-
Internal (gzip)	22.5 KB	-
Bundled (raw)	21.60 MB	-
Bundled (gzip)	3.42 MB	-
Import time	821ms	+8ms, +1.0%

🗺️ View treemap · Artifacts

Details

• Import time regressions over 10% are flagged with ⚠️
• Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.

📦 Bundle Stats — create-sanity

Compared against feat/api-command-list (309e558a)

Metric	Value	vs feat/api-command-list (309e558)
Internal (raw)	976 B	-
Internal (gzip)	507 B	-
Bundled (raw)	50.7 KB	-
Bundled (gzip)	12.6 KB	-
Import time	❌ ChildProcess denied: node	-

Details

• Import time regressions over 10% are flagged with ⚠️
• Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e28984b. Configure here.}

[cursor]

--operation flag silently ignored with --format=openapi

Medium Severity

The --format=openapi code path returns early at line 92–95, before selectOperations is called at line 97. This means --operation=<id> is completely silently ignored — neither applied nor validated — when combined with --format=openapi. A user passing --operation=nonexistentId --format=openapi receives the full spec YAML with no error or warning, contradicting the documented behavior and the command's own example description stating --operation "narrows any output mode to a single operation."

 

^{Reviewed by Cursor Bugbot for commit e28984b. Configure here.}

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/scripts/check-topic-aliases.ts	0.0% (±0%)
packages/@sanity/cli/src/api/docsClient.ts	96.0% (new)
packages/@sanity/cli/src/api/extractors.ts	83.5% (new)
packages/@sanity/cli/src/api/parser.ts	94.9% (new)
packages/@sanity/cli/src/api/views.ts	66.7% (new)
packages/@sanity/cli/src/commands/api/list.ts	97.3% (new)
packages/@sanity/cli/src/commands/api/spec.ts	100.0% (new)
packages/@sanity/cli/src/commands/openapi/get.ts	100.0% (±0%)
packages/@sanity/cli/src/commands/openapi/list.ts	100.0% (±0%)

Comparing 9 changed files against main @ 3e479c080419f692b9e2ff4719e30843435f04e6

Overall Coverage

Metric	Coverage
Statements	84.2% (±0%)
Branches	73.8% (- 0.3%)
Functions	84.5% (+ 0.5%)
Lines	84.8% (+ 0.2%)