Scribe Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Integration: Scribe is purpose-built for Laravel, leveraging its routing, validation, and resource layers. It extracts metadata from Laravel’s core components (e.g., FormRequest, API Resources, Transformers) to generate documentation, making it a first-class citizen in Laravel ecosystems.
• OpenAPI/Postman Alignment: Generates OpenAPI 3.0/3.1 specs and Postman collections, ensuring compatibility with modern API tooling. Supports custom content types (e.g., problem+json) and deprecated endpoints, aligning with API design best practices.
• Extensibility: Customizable via:
  • Strategies (e.g., response generation, validation parsing).
  • Annotations (e.g., #[Deprecated], #[BodyParam]).
  • Static overrides (e.g., manually defining endpoints not auto-detected).
• Dynamic Sample Responses: Can call endpoints during generation to fetch real responses (with event suppression for Eloquent models) or mock responses via factories/API resources.

Integration Feasibility

• Low Friction: Single Composer package (knuckleswtf/scribe) with zero runtime overhead (docs are pre-generated). No changes to existing API logic required.
• Dependency Compatibility:
  • Supports Laravel 10–13 (as of v5.8.0+).
  • PHP 8.1+ (with PHP 8.4 fixes in v5.7.0).
  • Compatible with Symfony YAML v8 (v5.9.0+).
• Toolchain Synergy:
  • Works alongside Laravel Forge, Envoyer, or Docker for CI/CD-generated docs.
  • Integrates with Postman, Swagger UI, or Redoc for consumption.

Technical Risk

Key Questions for TPM

1. API Complexity:
   • How many endpoints/routes require manual overrides (e.g., non-standard responses, legacy systems)?
   • Are there graphQL or WebSocket endpoints? (Scribe focuses on REST.)
2. CI/CD Workflow:
   • Should docs be generated on every deploy or nightly? (Affects storage/performance tradeoffs.)
   • Will docs be hosted internally (e.g., Laravel Forge) or externally (e.g., GitHub Pages)?
3. Tooling Ecosystem:
   • Is Postman or Swagger UI already in use? Scribe’s exports may reduce duplication.
   • Are there custom API clients (e.g., JavaScript SDKs) that need sync’d schemas?
4. Maintenance:
   • Who will curate doc quality (e.g., adding examples, fixing auto-generated descriptions)?
   • How will deprecated endpoints be managed (e.g., versioned docs)?

Integration Approach

Stack Fit

• Laravel-Centric: Ideal for RESTful APIs built with Laravel’s routing (routes/api.php), controllers, or resource classes.
• Complementary Tools:
  • Postman/Newman: Import Postman collections for testing.
  • Swagger UI/Redoc: Host OpenAPI specs for interactive docs.
  • API Clients: Generate SDKs (e.g., OpenAPI Generator) from the spec.
• Non-Laravel Considerations:
  • Legacy APIs: May require wrappers to expose Laravel-like routes.
  • Microservices: Can document individual services separately.

Migration Path

1. Pilot Phase:
   • Install Scribe in a staging environment:

     composer require knuckleswtf/scribe
     php artisan scribe:install
     

   • Generate docs for a subset of endpoints (e.g., /api/v1/users).
   • Validate OpenAPI/Postman exports against existing docs.
2. Full Rollout:
   • Configure scribe.php (e.g., disable response calls for unstable endpoints).
   • Set up CI/CD to regenerate docs on main branch pushes.
   • Deploy docs to a static host (e.g., Netlify, S3) or embed in Laravel’s /docs route.
3. Customization:
   • Extend with custom strategies (e.g., for GraphQL-like query params).
   • Override themes or add markdown examples via config/scribe.php.

Compatibility

Sequencing

1. Pre-Reqs:
   • Ensure Laravel routing, validation, and resource layers are stable.
   • Resolve circular dependencies in API logic (e.g., routes calling other routes).
2. Generation:
   • Run php artisan scribe:generate in a clean environment (avoid cached responses).
   • Use --no-response-calls for initial pass to avoid runtime issues.
3. Validation:
   • Compare auto-generated docs with manual specs (e.g., SwaggerHub).
   • Test Postman collection imports.
4. Deployment:
   • Host static files (HTML/JSON) separately from Laravel app.
   • Add cache headers (e.g., Cache-Control: max-age=86400) for performance.

Operational Impact

Maintenance

• Automated Updates:
  • Docs regenerate on code changes (via CI/CD). Minimal manual effort after setup.
  • Versioning: Use Git tags or Laravel’s APP_VERSION to track doc iterations.
• Manual Curations:
  • Examples: Add custom markdown examples for complex endpoints.
  • Descriptions: Override auto-generated text for clarity (e.g., intro_text in config).
  • Deprecations: Tag endpoints with @deprecated annotations.
• Dependency Management:
  • Update Scribe quarterly (align with Laravel’s LTS cycles).
  • Monitor for breaking changes in Laravel core (e.g., route parsing).

Support

• Troubleshooting:
  • Common Issues:
    • Missing endpoints: Check ignored_routes in config.
    • Broken responses: Disable response_calls or mock data.
    • Validation errors: Ensure rules are parsed correctly (e.g., sometimes).
  • Debugging Tools:
    • php artisan scribe:debug to inspect parsed routes.
    • Enable verbose mode in config for detailed logs.
• Stakeholder Training:
  • Developers: Teach how to annotate endpoints (e.g., #[Deprecated]).
  • API Consumers: Train on using the Try It Out panel and Postman exports.

Scaling

• Performance:
  • Large APIs (>500 endpoints):
    • Use --parallel flag for faster generation.
    • Exclude unstable endpoints via ignored_routes.
  • Response Generation:
    • Disable response_calls for non-critical paths.
    • Use factories for mock data instead of live calls.
• Storage:
  • Docs are static files (~1–5MB per 100 endpoints). Host on:
    • Cheap static hosts: S3, Cloudflare Pages.
    • Laravel’s /docs route: Serve via public/docs folder.
• Parallelization:
  • Scribe supports parallel route processing (configurable via parallel in scribe.php).

Failure Modes