fix(Augmenter): report a response component named after a status code - #2182
Merged
DerManoMann merged 1 commit intoSep 11, 2026
Merged
Conversation
`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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
A response that fails to nest into its operation disappears from the document with nothing
said, in the default configuration.
Response::$responsecarries two meanings: the HTTP status code when the response is nestedin an operation, and the component name when it sits in the
responsesbucket.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\Cleanupremoves it as unused, and the author's response is gone without a diagnostic.
A reusable response named
200is a failed merge every time, and it is the only part ofthis a user can see. Reporting it turns a silent drop into a pointer.
Changes
Augmenter\Cleanupwarns when the unreferenced component it removes is aResponsewhosekey looks like a status code, naming the source location. What gets removed is unchanged.
— 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.
Spec\Response, so the compiler'sRESPONSE_KEYandthe augmenter share one copy instead of carrying the regular expression twice.
CleanupTestcovering the status code, a range,default, a named componentremoved silently, and a referenced status-code key that is kept.
Note
With
cleanup.enabledset tofalsenothing warns, because the component survives into theoutput where it is at least visible. Extending the compiler's
validateResponses()to thecomponents bucket would cover that case too, but the compiler cannot see whether a component
is referenced, so it would also report a deliberately named
200that an operation$refs.That is part of the wider question of whether a component key may double as a value, which
also governs
PathItemandMediaType, and is better settled once than guessed at here.