Skip to content

feat(Builder): add withSpecification(), a contribution seam before resolution - #2218

Merged
DerManoMann merged 2 commits into
zircote:masterfrom
DerManoMann:feat/specification-contribution
Sep 27, 2026
Merged

DerManoMann merged 2 commits into
zircote:masterfrom
DerManoMann:feat/specification-contribution

Conversation

@DerManoMann

@DerManoMann DerManoMann commented Sep 26, 2026 •

Copy link
Copy Markdown
Collaborator

Overview

Metadata that describes an API but has no reflector cannot reach the spec pipeline.
A translator turns one attribute into another and needs something to read it off; an
entity registry or a serializer's configuration carries no attribute anywhere. The
only way in today is an augmenter, which runs after resolution, so a $ref inside
what it adds stays unresolved.

Builder::withSpecification() hands the assembled Specification to a callable
between assembly and resolution. What it adds is resolved, augmented and compiled
with the scanned sources. The pipeline reads a reflector, not a source file, so a
contribution that carries one gets the scanned treatment, docblocks and parameter
types included, and one without gets an operation id from method and path since
there is no declaring code to name.

With a second deferred hook on Builder, the docblocks' silence on when each hook
runs and whether repeated calls accumulate became ambiguous, so each one now says.

Changes

  • Add Builder::withSpecification(), with SpecificationContributionTest
  • Derive an operation id from method and path in OperationIds for an operation
    with no reflector
  • State on every Builder hook when it runs and whether repeated calls accumulate
    or replace
  • Add "Contributing to the Specification" to the extension-points guide, with an
    executed snippet and its expected output
  • Add the hook to the builder reference and the modes table
  • Drop the builder reference's closing example, which repeated the page's other
    snippets

…solution

Builder::withSpecification() registers callables that receive the assembled
Specification between assembly and resolution; hooks accumulate and run in
registration order. OperationIds derives an id from method and path for an
operation with no reflector. Each Builder hook's docblock states when it
runs and whether repeated calls accumulate or replace.

The extension-points guide gains a contributions section with an executed
snippet, the builder reference and modes table gain the hook, and the
builder reference's closing example is removed.
The extension-points guide, the builder reference and the withSpecification()
docblock describe contributions as attributes the assembler did not build,
with or without a reflector, rather than as reflector-less metadata only.
SpecificationContributionTest covers an operation and parameters contributed
with their reflectors, against a new attribute-free PlainController fixture.
@DerManoMann
DerManoMann merged commit a0297f5 into zircote:master Sep 27, 2026
19 checks passed
DerManoMann added a commit to DerManoMann/openapi-introspector that referenced this pull request Sep 27, 2026
withSpecification() merged as zircote/swagger-php#2218, so the fork's branch and
the path repository at ../swagger-php have nothing left to provide: packagist
serves dev-master at the same commit. Dropping the repository is what lets a
plain `composer install` work anywhere, CI included.

dev-master rather than a caret because the seam is merged but unreleased; this
becomes ^6.x when the minor carrying it tags.
@DerManoMann
DerManoMann deleted the feat/specification-contribution branch September 27, 2026 04:16
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