Behat Nelmio Describer Laravel Package

Product Decisions This Supports

• Documentation drift as a first-class product risk. This package wires Behat's test-time sample responses into Nelmio API Doc output, so the "example response" a partner developer sees in your docs is the payload your test suite actually asserted on. The decision it enables: do we treat API documentation as a tested artifact or as a manually curated artifact? That choice determines whether docs get stale between releases and how much support load your API generates.
• Build vs. buy on the "docs-from-tests" glue layer. This is a thin integration between two existing tools you likely already run (Behat for behavior tests, NelmioApiDocBundle for docs). It is not a platform. The real decision is whether to (a) fork and vendor a small internal copy, (b) reimplement the ~few-hundred-line describer in-house, or (c) skip examples-in-docs entirely and publish an OpenAPI spec that examples are generated into at build time. The v2.0.1 release (Symfony 7.0 support) lowers the cost of option (a) for teams modernizing onto Symfony 7, but does not change the underlying shape of the decision.
• Roadmap input for public/partner API surfaces. If your roadmap includes a developer portal, partner integrations, or auto-generated SDKs, accurate example payloads are a prerequisite. This package is evidence that the capability exists and is cheap — useful for scoping that roadmap item without committing to an unmaintained dependency. The Symfony 7 work means this scoping exercise is still valid for teams on current LTS stacks, not just legacy ones.
• Support-deflection and onboarding use cases. Real sample responses in docs reduce "what does this endpoint actually return?" tickets and shorten partner time-to-first-call. Estimating that benefit is a product decision, not an engineering one.
• Prioritizing test-suite investment. Adopting this pattern only pays off if Behat coverage is broad enough that the captured examples are representative. It gives you a concrete, visible justification for funding behavior-test coverage — the tests stop being invisible insurance and start producing a customer-facing artifact.
• Deprecation and versioning policy. Because examples come from tests, changing an endpoint's behavior immediately changes the published example. That forces an explicit decision about whether examples are versioned alongside the API or always reflect main. The package's own major-version bump (v2.0.0 → v2.0.1) is a reminder that the tooling has a version cadence separate from your API's, and pinning matters.

When to Consider This Package

Adopt (typically as a fork or vendored copy, not a Composer dependency):

• You are already standardized on Behat for API behavior tests and NelmioApiDocBundle for documentation, on a Symfony application.
• You are on Symfony 7.0. The v2.0.1 release adds Symfony 7 support, so the previous "legacy stack only" constraint no longer applies. This is the single most material change since the last assessment: the addressable window for the capability now includes current-generation Symfony apps.
• You are on an older Nelmio generation (annotation/@ApiDoc-era or early attribute support) that lacks first-class per-response example handling.
• You need example payloads now and the alternative is a multi-sprint homegrown tool.
• You can accept ownership. Re-verify repo status before depending on this assessment: the prior read characterized the repository as archived with two stars, zero dependents, and a December 2023 last release. The v2.0.1 publication contradicts at least part of that picture — the project is receiving maintenance (Symfony 7 compatibility, merged PR, tagged release). Treat the updated signal as "lightly maintained, single-maintainer, low adoption" rather than "dead." That still means: budget for maintenance, PHP/Symfony version upgrades, and eventual replacement, and copy the source rather than pinning a supply-chain dependency.
• You can tolerate a narrow support matrix. A version-compatibility bump is not a support commitment; there is still no published security-response process or SLA.

Look elsewhere when:

• You are OpenAPI-first / schema-first. Generate examples into the spec in CI (fixtures, contract tests, or a schema validator) rather than through a test-runner extension. Tooling like Schemathesis, Dredd, or a plain OpenAPI linter plus fixture injection covers this with a larger community.
• You are on modern NelmioApiDocBundle, which supports examples on models and responses directly. Reimplementation cost is low; the package's value proposition shrinks to near zero. This remains true and is strengthened by Symfony 7 support — the framework you'd be on with modern Nelmio is now also the framework this package supports, so the comparison is apples-to-apples.
• You are not on Symfony, or you do not run Behat. Neither dependency is worth acquiring for this capability.
• You need vendor support, a security-response process, or an SLA. A compatibility release does not create any of these — this alone disqualifies it for regulated or customer-facing contractual surfaces.
• Your Behat suite is thin or non-representative. Bad tests produce misleading examples, which is worse than no examples.
• You want contract enforcement, not just documentation. This package publishes examples; it does not validate that the implementation matches the spec. Pair with a real contract-testing step or you get docs that look authoritative but diverge silently.

How to Pitch It (Stakeholders)

Executive summary: This package is a small, lightly maintained integration that makes API documentation show real, test-verified response payloads instead of hand-written examples. The idea is worth adopting; the dependency still probably is not. A new release (v2.0.1) adds Symfony 7 support, which extends the capability's useful life onto current-generation stacks and softens — but does not remove — the maintenance concern. It remains low-adoption with no support or security commitments, so it represents an engineering pattern to copy, not a vendor to rely on. Recommendation: run a short, time-boxed spike to validate that examples-from-tests materially improves API developer experience, then implement the small piece of glue internally or on top of modern Nelmio example support rather than adding this package to the build.

For engineering: The mechanism is straightforward — a Behat extension/context that captures sample responses during test runs and a Nelmio describer that surfaces them in the generated documentation. Expect the integration surface to be small and highly coupled to your Nelmio and Symfony versions, which is precisely why a fork beats a dependency here. The v2.0.1 changeset is a version-compatibility bump only — no new features, no behavioral changes, no deprecations — so it does not alter the integration design, but it does confirm that the Symfony-version coupling is the live maintenance cost. Two caveats to design around: examples become a public artifact with a release cadence, and the package does not validate responses against a schema — it only publishes them. If contract accuracy matters, that needs a separate enforcement step in CI.

Cost and risk: Near-zero licensing or procurement cost (MIT); the real cost is ownership and the upgrade treadmill. The new release modestly reduces one risk (framework-version obsolescence, now including Symfony 7) while leaving the other risks intact: documentation that looks authoritative while being derived from incomplete tests, and orphaned code if the single maintainer stops. Both remain manageable if the capability is owned by a team and scoped as a documentation-quality initiative rather than a product dependency. Do not read a compatibility release as a support guarantee.