Skip to content

fix(Augmenter): report a response component named after a status code - #2182

Merged
DerManoMann merged 1 commit into
zircote:masterfrom
DerManoMann:fix/response-component-key
Sep 11, 2026
Merged

fix(Augmenter): report a response component named after a status code#2182
DerManoMann merged 1 commit into
zircote:masterfrom
DerManoMann:fix/response-component-key

Conversation

@DerManoMann

Copy link
Copy Markdown
Collaborator

Overview

A response that fails to nest into its operation disappears from the document with nothing
said, in the default configuration.

Response::$response carries two meanings: the HTTP status code when the response is nested
in an operation, and the component name when it sits in the responses bucket. isRoot()
cannot separate them — it is true whenever the key is set. So a response that does not nest
becomes a component named after its status code, nothing references it, Augmenter\Cleanup
removes it as unused, and the author's response is gone without a diagnostic.

A reusable response named 200 is a failed merge every time, and it is the only part of
this a user can see. Reporting it turns a silent drop into a pointer.

Changes

  • Augmenter\Cleanup warns when the unreferenced component it removes is a Response whose
    key looks like a status code, naming the source location. What gets removed is unchanged.
  • Keying the check to removal keeps it precise: an unreferenced reusable response is ordinary
    — a library may declare more than any one document uses — so only a status-code-shaped key
    is reported, and a deliberately named component that is referenced stays silent.
  • The status-code pattern moves onto Spec\Response, so the compiler's RESPONSE_KEY and
    the augmenter share one copy instead of carrying the regular expression twice.
  • Four tests in CleanupTest covering the status code, a range, default, a named component
    removed silently, and a referenced status-code key that is kept.

Note

With cleanup.enabled set to false nothing warns, because the component survives into the
output where it is at least visible. Extending the compiler's validateResponses() to the
components bucket would cover that case too, but the compiler cannot see whether a component
is referenced, so it would also report a deliberately named 200 that an operation $refs.
That is part of the wider question of whether a component key may double as a value, which
also governs PathItem and MediaType, and is better settled once than guessed at here.

`Response::$response` is the status code when the response nests in an operation
and the component name when it does not, so a response that fails to nest lands in
`components.responses` under its code. Nothing references it, `Cleanup` removes it,
and the response disappears with nothing said.

`Cleanup` now warns when the component it removes is a `Response` whose key looks
like a status code. Removal is unchanged, and a named component stays silent.

Move the status-code pattern onto `Spec\Response` so the compiler and the augmenter
share one copy.
@DerManoMann
DerManoMann merged commit 211dd56 into zircote:master Sep 11, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant