Geni Api Laravel Package

Getting Started

This package turns your Laravel routes/actions into generated API documentation. The v3.1.0 release is a small follow-up to 3.0, so the upgrade path is trivial — existing committed specs stay valid.

1. Install and publish the config so you can see what the generator reads:

   composer require <vendor>/geni
   php artisan vendor:publish --tag=geni-config   # creates config/geni.php
   

2. Annotate a single endpoint first — pick a controller method or a Laravel Action and give it a PHPDoc block. In 3.1 you can control the operation title explicitly:

   /**
    * @summary Create a new invoice
    *
    * Issues an invoice and queues the PDF render.
    */
   public function store(StoreInvoiceRequest $request) { ... }
   

3. Generate and open the output (php artisan geni:generate, or whatever your app's command wrapper is) and check the title renders as Create a new invoice rather than the class name.
4. Only then scale out — walk the route list (php artisan route:list) and annotate in order of traffic/consumer importance rather than alphabetically. The first real use case is almost always "give the frontend/mobile team a stable contract for the endpoints they call today."

Where to look first when something is off: the published config/geni.php (renderers and output paths), then the PHPDoc block itself. The generator is annotation-driven — most surprises are a tag that isn't being read, not a package bug.

Implementation Patterns

Title precedence is the core 3.1 pattern. Three sources now compete for an operation's title, in this order:

1. #[Endpoint(title: '...')] attribute — highest priority, keeps the title next to the route definition and is greppable.
2. @summary PHPDoc tag — new in 3.1, lets you override the title without touching the attribute or restructuring the docblock.
3. First paragraph of the PHPDoc block (existing 3.0 behavior), falling back to the class name for Laravel Actions that have neither.

Practical split: use #[Endpoint(title: ...)] where the title is genuinely part of the endpoint's identity (and you want IDE/static-analysis visibility), and reach for @summary when the title is just a human-friendly rewrite of a long first paragraph. A common, low-churn pattern is to keep the descriptive opening paragraph for humans and add @summary for the rendered heading:

/**
 * Validates the payload, checks the customer's credit limit, and
 * hands off to the billing queue. This paragraph is long on purpose.
 *
 * @summary Create invoice
 */

Laravel Actions. Actions without @summary keep deriving the title from the class name — so 3.0.x action docs don't change when you upgrade. If you have an Action per use case (CreateInvoiceAction, RefundInvoiceAction), the derived titles are usually fine and you should not add @summary everywhere "for consistency." Add it only where the class name reads badly in a rendered doc (e.g. abbreviated or jargon-y names).

Annotate at the boundary. Put the docblock on the public entry point (controller method or handle()/__invoke() on the action), not on form requests, resources, or DTOs — those aren't the operation. This keeps the generator's input predictable and diff review of API changes concentrated in one file per endpoint.

Generation in CI. Treat the generated spec as a build artifact: regenerate in CI and fail the build if the committed output differs (git diff --exit-code). That catches the real failure mode — someone changing a route or docblock and forgetting to regenerate — without forcing everyone to run the command locally as a pre-commit hook.

Integration tip. Because output is committed and diffable, review generated spec changes in PRs exactly like code. A @summary added in this release will show up as a one-line title change in the diff, which is a good, cheap signal that the change was intentional.

Gotchas and Tips

• The 3.1 config removals are inert. api_domain, security_strategy, and renderers.blade.dark_mode were never read, so leaving them in your published config/geni.php changes nothing. Clean them out opportunistically to avoid the "this config key must do something" trap for the next person, but don't schedule a migration for it.
• Title precedence surprises. If you add @summary and see no change, check for an #[Endpoint(title: ...)] attribute on the same class/method — the attribute always wins. Conversely, if a title looks like a truncated sentence, it's the first PHPDoc paragraph; @summary is the fix.
• "No behavior changes" is true only if you don't start using @summary. The moment you adopt it, titles in the generated spec change, and any consumer doing snapshot/golden-file testing against the spec will see diffs. Land @summary adoption as its own commit so those diffs are isolated and reviewable.
• Doc comment rewording is not behavior… except when it is. 3.1 reworded README/config/code comments to stop referring to other documentation generators. Harmless here, but be aware that in a PHPDoc-driven generator, comments are input. Keep the rule simple: prose that lives in a docblock on a routed method is data; prose in the package's own source is not.
• Config caching. If you change config/geni.php in a deployed environment, remember php artisan config:cache — a stale cached config is the most common reason a config edit "doesn't work."
• Debugging a missing endpoint. Verify the route is registered (route:list) and the docblock sits on the method actually referenced by the route — not a parent class method, and not behind a closure. Closures and invokable anonymous handlers have nowhere to hang a docblock, so they generally won't pick up @summary or #[Endpoint] metadata.
• Extension point to watch. renderers.* in config is where output format lives. If you need a custom shape (internal portal, typed client generation), reach for a renderer rather than post-processing generated files — post-processing gets silently clobbered on the next regeneration.