Geni Api Laravel Package

Product Decisions This Supports

• API documentation as a shipped artifact, not a wiki chore. Geni generates the API spec from the Laravel codebase itself, so the docs track the code. For a PM this converts "documentation drift" from an ongoing cost into a build-time check — relevant to any roadmap item that promises a public or partner-facing API.
• Public API / partner integration launches. Stable, explicit operation titles are a prerequisite for readable reference docs, generated SDKs, and search results. v3.1.0's @summary tag makes operation titles an explicit product decision rather than an accident of class naming, which matters the moment an external audience sees the spec.
• Build vs buy on developer documentation. With this release, the package stops positioning itself against other documentation generators and simply generates the spec. That clarifies the buying decision: Geni is the source of truth generator, while hosted portals (Readme, Mintlify, Redocly, Stoplight) are the presentation layer. Budget them as two line items, not competing ones.
• Roadmap sequencing for "developer experience" work. The @summary tag is small but is the kind of primitive that unblocks later commitments — consistent SDK method names, changelog entries keyed to operation IDs, and deprecation notices that point at a stable identifier. Worth slotting before, not after, a public API GA.
• Migration/upgrade budgeting. The release explicitly keeps existing committed specs valid. That means the upgrade can ride along with routine maintenance rather than needing its own sprint — a favourable input to any "can we do this this quarter" conversation.
• Config surface rationalisation. Removing never-read keys (api_domain, security_strategy, renderers.blade.dark_mode) is a signal the config file is being treated as a contract. For a PM, a shrinking, honest config surface is a proxy for maintainability and lowers the cost of onboarding new engineers onto the API layer.

When to Consider This Package

Consider adoption when:

• The product exposes an HTTP API to customers, partners, or internal consuming teams, and the spec is expected to be accurate rather than aspirational.
• The codebase is Laravel and already leans on Laravel Actions or controllers with PHPDoc/attributes — Geni reads what is there rather than demanding a parallel annotation dialect.
• You need the spec to be a build artifact: generated in CI, diffed on pull requests, and consumed by downstream tooling (SDK generation, contract tests, portals).
• You want operation titles to be a deliberate, reviewable choice. @summary in the PHPDoc is a low-ceremony way to let the API owner name an operation without forcing an attribute everywhere; #[Endpoint(title: ...)] still wins where you want it enforced at the code level.
• The team is small and cannot sustain a hand-maintained OpenAPI file. Automation is the only realistic path to documentation that survives a busy quarter.

Look elsewhere when:

• The API is not Laravel, or is Laravel but specified contract-first in a design tool — in that case the spec is the input, not the output, and a generator inverts your workflow.
• You need the portal: search, try-it consoles, versioned public docs, custom domains, analytics. Geni produces the document; you still need a renderer or hosted product in front of it.
• You have no CI discipline. A generator without a "spec must be committed and unchanged" check simply produces stale files faster.
• You are pre-product-market-fit with an internal-only API and no external consumers. The payoff is real but deferred; revisit when the first integration partner appears.
• You expect the config file to be deeply customisable. This release removed unused keys rather than adding knobs — the package's direction is convention over configuration, and teams wanting fine-grained control over rendering should plan for a downstream tool.

How to Pitch It (Stakeholders)

For executives — one paragraph. We generate our API specification directly from the Laravel code rather than maintaining it by hand, which removes a recurring source of customer-facing inaccuracy and a recurring manual cost. The latest release (v3.1.0) is a small, low-risk follow-up: it adds a way for engineers to name an API operation explicitly so public documentation and any generated client libraries use a stable, human-readable name instead of an inferred one, it trims configuration options that never did anything, and it deliberately does not change the output for anything we already generate. There is no migration project attached — existing generated specs remain valid, so this can land inside normal maintenance. The strategic point is that API documentation stops being a document we maintain and becomes an artifact we produce, which is the precondition for any credible public-API or partner-integration commitment on the roadmap.

For engineering — the practical case. Upgrade is a no-op unless we choose to use it. The @summary PHPDoc tag lets us set an operation title per endpoint, with #[Endpoint(title: ...)] still taking precedence where we want a harder guarantee; endpoints without either keep today's class-name-derived titles, so adoption can be incremental and per-endpoint. The three removed config keys were never read, so a published config/geni.php containing them is inert — no action needed, though it is worth deleting them so the file stops implying capabilities we do not have. The documentation rewrite that drops references to other generators is positioning only, not behaviour. Recommend: upgrade in the next dependency sweep, add a CI step that fails when the committed spec drifts from the code, and introduce @summary first on the endpoints that external consumers actually call.

For design/developer-relations — the user-visible part. Operation titles are the single most-read string in an API reference. Being able to set them explicitly means the docs say what we decided they should say, in the language our users use, rather than exposing an internal class name. That is a small change with an outsized effect on how finished the API looks.