Scribe Laravel Package

Product Decisions This Supports

• API Documentation as a First-Class Product Feature:

  • Automatically generate human-readable API docs (HTML, OpenAPI, Postman) directly from Laravel code, reducing manual documentation effort by 80%+.
  • Enable self-service developer onboarding with interactive "Try It Out" panels, reducing support tickets for API usage.

• Developer Experience (DX) Roadmap:

  • Replace Swagger/OpenAPI tools (e.g., Swagger UI, Redoc) with a native Laravel solution that integrates with existing validation, FormRequests, and API Resources.
  • Accelerate API adoption by frontend/mobile teams with zero-config examples (e.g., sample requests/responses from Eloquent models or factories).
  • Support API-first development by surfacing docs as part of CI/CD pipelines (e.g., auto-generate docs on git push to main).

• Build vs. Buy Decision:

  • Buy: Avoid reinventing the wheel for OpenAPI generation, validation parsing, or interactive docs. Scribe handles Laravel-specific edge cases (e.g., FormRequests, API Resources) out of the box.
  • Customize: Extend with hooks (e.g., afterExtracting) or custom strategies to adapt to non-standard APIs (e.g., GraphQL-like endpoints, WebSocket routes).
  • Cost: Free (MIT license) with no vendor lock-in; no recurring fees or proprietary formats.

• Key Use Cases:

  • Internal APIs: Document microservices or monolith endpoints for backend teams.
  • Partner/3rd-Party APIs: Generate public-facing docs with OpenAPI/Postman exports.
  • Legacy APIs: Retrofit docs to existing Laravel apps without manual annotation.
  • API Versioning: Support parallel OpenAPI 3.0/3.1 specs for backward compatibility.
  • Deprecation Management: Mark endpoints as @deprecated with UI badges (e.g., for sunsetting old routes).

When to Consider This Package

Adopt Scribe If:

• Your API is built with Laravel (routes, FormRequests, validation, API Resources, or Transformers).
• You need interactive docs (e.g., "Try It Out" panels) without integrating third-party tools like Swagger UI.
• Your team prioritizes automation over manual doc maintenance (e.g., Postman collections or Markdown files).
• You require multi-format exports (HTML, OpenAPI, Postman) from a single source of truth.
• Your API uses Eloquent models/factories for responses, and you want auto-generated examples.
• You need deprecation support (e.g., flagging endpoints as @deprecated in docs).
• Your stack includes Laravel 10+ (Scribe supports up to Laravel 13 as of v5.10).

Look Elsewhere If:

• Your API is not Laravel-based (e.g., Node.js, Python, Go). Use Swagger/OpenAPI tools (e.g., swagger-ui-express, connexion) or custom scripts.
• You need GraphQL docs: Use GraphQL tools (e.g., GraphiQL, Apollo Studio) or Scribe’s custom strategies for hybrid APIs.
• Your API is highly dynamic (e.g., runtime-generated routes). Scribe relies on static route extraction.
• You require advanced security definitions (e.g., OAuth2 flows beyond basic API keys). Scribe supports basic security schemas but may need extension.
• Your team prefers Markdown/Postman-only workflows. Scribe’s HTML output is designed for developers, not marketing sites.
• You need real-time docs (e.g., WebSocket subscriptions). Scribe focuses on REST/HTTP APIs.

How to Pitch It (Stakeholders)

For Executives (Business/Tech Leads):

"Scribe eliminates the $50K/year cost of manual API documentation by auto-generating interactive, always-up-to-date docs from our Laravel codebase. With zero maintenance overhead, frontend teams can self-serve API examples (e.g., ‘Try It Out’ panels), reducing onboarding time by 60%. It also future-proofs our APIs with OpenAPI/Postman exports for partners—all while cutting dev time spent on Swagger annotations or Postman collections by 75%."

Key Outcomes:

• Faster API adoption: Devs get docs automatically with every code push.
• Lower support costs: "Try It Out" panels reduce "How do I call this endpoint?" questions.
• Partner-ready: Export OpenAPI/Postman specs for third-party integrations without manual work.
• Scalable: Works for 10 endpoints or 10,000—no manual scaling needed.

For Engineering (Devs/Architects):

*"Scribe turns your Laravel API into self-documenting code. No more:

• Writing Swagger annotations by hand.
• Maintaining Postman collections in sync with routes.
• Debugging stale Markdown docs.

How it works:

• Auto-discovers routes, validation rules, and API Resources.
• Generates examples from Eloquent models/factories (no mock data needed).
• Exports to HTML (interactive), OpenAPI (3.0/3.1), or Postman.
• Extensible: Add custom strategies for edge cases (e.g., GraphQL-like endpoints).

Tech Deep Dive:

• Parses FormRequests and validation rules for request params.
• Calls endpoints safely to fetch real response examples.
• Supports deprecation tags, custom response types, and Blade syntax in configs.
• Hooks (e.g., afterExtracting) let you modify extracted data before rendering.

Migration Path:

• Drop-in install (composer require knuckleswtf/scribe).
• Configure scribe.php (5-minute setup).
• Run php artisan scribe:generate in CI/CD.

Why not [Alternative X]?

• Scribe is Laravel-native (handles FormRequests, API Resources, etc.).
• Interactive HTML > static Markdown/Postman.
• No vendor lock-in (MIT license, OpenAPI exports)."*

Dev-Focused Benefits:

• No boilerplate: Docs update automatically with code changes.
• Debug-friendly: "Try It Out" panels test endpoints live.
• Future-proof: Supports OpenAPI 3.1 and Laravel 13.
• Customizable: Override defaults via hooks or custom strategies.