Scribe Laravel Package

Product Decisions This Supports

• Build vs. buy for API documentation. Scribe is MIT-licensed and installs as a Composer dev dependency, so the "buy" side is effectively free and the decision reduces to build (hand-maintained docs) vs. adopt (generated docs) vs. adjacent tooling. Frame the comparison against (a) a technical writer maintaining Markdown, (b) a spec-first OpenAPI workflow, and (c) the zero-annotation Laravel alternative (Scramble).
• Feature/roadmap: shipping the OpenAPI artifact. The headline capability for planning is not the HTML page — it's that the same run emits OpenAPI 3.0.3 or 3.1.0 and a Postman collection. That spec is a reusable asset that unblocks downstream roadmap items: SDK/client generation, API gateway import (Kong, AWS API Gateway), contract testing, partner onboarding, and embedding in an existing developer portal or Redoc/Swagger UI. Decide once whether Scribe is your docs product or your spec factory; the second is the higher-leverage answer.
• Partner/B2B integration readiness. If a sales or partnerships conversation depends on "do you have API docs we can evaluate?", this is the shortest path to a credible answer — one page with human-readable text, code samples, and an in-browser tester.
• Versioning and deprecation strategy. Native support for @deprecated / [#Deprecated] annotations and a deprecation badge means you can communicate API lifecycle commitments, not just document endpoints. Useful when negotiating sunset timelines with integrators.
• Support-cost reduction / prioritization. Generated docs plus "Try It Out" shift debugging from your team to the consumer. Treat doc coverage as a metric: how many of your v1 endpoints have accurate params, examples, and auth documented — that number feeds support-ticket triage and roadmap prioritization.
• Use-case fit to validate before committing: internal platform APIs, mobile-client backends, partner-facing REST APIs, QA/CS onboarding, and pre-sales demos. Less relevant if your surface is GraphQL, gRPC, or event-driven (AsyncAPI) — Scribe is REST-focused.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP (5.x line tracks current Laravel through Laravel 13 and PHP 8.4 compatibility — verify your version against releases).
• The team already writes FormRequests or inline validation rules — Scribe extracts request parameters from them, so docs are a byproduct of code you're writing anyway, not a second source of truth.
• You use Eloquent API Resources / Transformers, so sample responses can be derived rather than invented.
• You need OpenAPI output without converting the org to a design-first/spec-first workflow.
• You have a single deployable or a small number of Laravel services, and can run generation in CI.
• MIT licensing, no vendor contract, and no procurement cycle matter to you.

Look elsewhere when:

• Polyglot or non-Laravel estate. The value proposition collapses outside Laravel; a spec-first or multi-language generator is the better org-wide standard.
• Governance mandates design-first. If an API council or external partner requires review of the contract before implementation, generating docs from built code is backwards.
• You need a docs portal, not docs. No built-in hosted site with product/version navigation, access control for private APIs, search across products, or usage analytics. Plan to publish the HTML/spec into your own hosting.
• Accuracy is a hard requirement. Generated docs describe intent; they don't enforce it. If contract drift is the real risk, invest in contract tests or spec validation — Scribe is complementary, not a substitute.
• "Call endpoints to get sample responses" is unacceptable. This is the feature most likely to fail security or data-governance review. Confirm you can point it at a seeded sandbox with side effects disabled, or turn it off.
• No appetite for ongoing annotation upkeep. Docs that silently rot are worse than none; if nobody owns the pipeline, don't start it.
• Very large monoliths where generation time or diff noise becomes a CI tax — pilot to measure.

Also compare against Scramble (Laravel, zero-annotation) and against hand-rolled OpenAPI. Scribe's differentiators are its UI quality, Postman output, and extensibility via custom extraction strategies.

How to Pitch It (Stakeholders)

For executives: Scribe generates API documentation directly from our Laravel codebase — no license cost, no new vendor, roughly a couple of engineer-days to pilot. It produces a human-readable docs page with an interactive tester and an OpenAPI spec, which is the asset that lets us generate client SDKs, import into an API gateway, and onboard integration partners faster. The business case is reduced integration friction and fewer support tickets, at near-zero run cost. The main risk is not technical, it's operational: docs are only as good as the discipline behind them, so we should timebox a pilot and assign an owner.

For engineering: One Composer dependency, one Artisan command, a publishable config file. It reads our existing FormRequests and validation rules instead of duplicating them, derives sample responses from API Resources, and emits OpenAPI 3.1 and a Postman collection we can commit or publish in CI. It's extensible via custom strategies and post-extraction hooks if the defaults don't fit, and the project is actively maintained across current Laravel and PHP releases. Caveats we should own up front: response-call generation must point at a seeded sandbox, and endpoint-level annotations will need upkeep.

The ask: a timeboxed pilot on one API surface — integrate, generate, review output quality against the real contract, and measure generation time in CI — before committing to org-wide adoption.