feat(Spec): add component:, one key field on every reusable attribute - #2219
Merged
Merged
Conversation
- `component` on the ten reusable Spec types; the historic key fields alias onto it — in the constructor where the field can only be the key, and in `ComponentName::normalise()` where it is also a nesting key - `ComponentName::of()` reads `component`; `isRoot()` follows it on the conditionally-root types - `PathItem` and `MediaType` gain the field and their `components` buckets; `compilePathItem()` emits `$ref` - a schema's title is no longer a key fallback - historic spellings `@deprecated`, removed in 8.0, with a runtime deprecation - fixtures, examples and docs on the new spelling; reference regenerated
…th Spec The Components rewrite described the new key from inside `Spec`: "before 6.11 each type spelled its key after itself". Those spellings -- `schema`, `parameter`, `request`, `securityScheme` -- are also classic's, current and not deprecated, so a classic reader met their own field names under a deprecation notice with nothing saying classic is untouched. It is: the bridge maps them to `component` directly and `ComponentName::normalise()` only reports for specifications the user wrote. The migration path said the opposite of what now happens. Step 2 offered `OpenApi\Spec` as a change of namespace, and the v8 line priced the move at "one `use` line per file" -- the ROADMAP sentence with its scoping clause dropped. Coming from classic it is that plus every component key. - modes.md step 2 names the four classic spellings that become `component:` - modes.md v8 line scoped the way `ROADMAP.md` scopes it, with the classic case spelled out - the guide's deprecation warning states that classic reports nothing, and where the cost actually lands Spec is still beta, so the deprecation inside it is the smaller half of this.
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
Each reusable spec attribute spelled its component key after its own type —
schema:,response:,parameter:,header:and so on — and for four of them the same field was also the key the attribute nests under:response: 200is a status code in an operation and a component name incomponents.responses, andheader,linkandexamplebehave the same way. The object cannot tell which it holds, soisRoot()guessed from field presence,RequestBody,Response,ParameterandLinkeach drew the key-plus-refline differently, and a response that failed to nest became a component named200with nothing said untilCleanupnoticed.One field,
component, names the key a reusable attribute is filed under, on every type — includingPathItemandMediaType, which had no key at all and could not be reused. The value fields keep their value, the identity has its own field, and the root rule is one rule: keyed means root, and key-plus-refis either a nested reference or an aliasing component.The historic spellings keep working through 8.0 and produce the same document — every fixture and example moved to the new spelling with its expected output unchanged — and trigger a deprecation once. Only their use as a component key is deprecated;
response: 404on a nested response orheader: 'X-Rate-Limit'on a header inside one is the nesting key and stays. Classic is untouched and reports nothing — the bridge maps its keys tocomponentdirectly — but the classic → spec migration is now a key rename as well as a change of namespace, so it is no longer the oneuseline per file the migration path promised.Changes
component:onSchema,Response,Parameter,RequestBody,Header,Link,Example,Security\Scheme,PathItemandMediaTypeComponentName::of()answers withcomponent;ComponentName::normalise()fills it from the historic spellings once per build, before the resolver's first indexisRoot()followscomponenton the conditionally-root types; a keyedHeaderorExamplestands alone withoutComponentsPathItemwith a key is acomponents.pathItemsentry and governs no class; 3.0 reports and omits itMediaTypewith a key is acomponents.mediaTypesentry from 3.2; earlier versions report and omit itcompilePathItem()emits$ref@deprecated, removed in 8.0, with a runtime deprecation;ROADMAP.mdlists themAugmenter\Names,Enums,Refs,Inheritance\Schemasand the compiler diagnostics readcomponentHybridBridgepassescomponentdirectly, so classic input never reportsComponentNameTestandReusableComponentsTestaddeddocs/dev/pipeline.mdroot taxonomy and the guide's Components section rewritten;reference/spec-attributes.mdregenerateddocs/guide/modes.mdmigration path names the four classic spellings that becomecomponent:, and its v8 line is scoped the wayROADMAP.mdscopes it — oneuseline per file for code already onOpenApi\Spec, plus the component keys coming from classic; the guide's deprecation warning states that classic reports nothing