Opendox Laravel Package

Getting Started

1. Install via Composer

   composer require noitran/opendox
   

   Laravel 5.5+ auto-discovers Noitran\OpenDox\Providers\OpenDoxServiceProvider. For Lumen, register it manually in bootstrap/app.php:

   $app->register(\Noitran\OpenDox\Providers\OpenDoxServiceProvider::class);
   

2. Publish the config (Laravel):

   php artisan vendor:publish --tag=opendox
   

   Lumen users should copy the config into config/opendox.php themselves and call $app->configure('opendox'); before the provider registration.

3. Point the package at your annotated code. Open config/opendox.php and set the paths/globs the swagger-php scanner should crawl (typically your app/Http/Controllers and any app/OpenApi schema files). Set the title, version, servers, and the output path for the generated JSON.

4. Add your first annotation to a controller:

   /**
    * @OA\Get(
    *   path="/api/users",
    *   tags={"Users"},
    *   @OA\Response(response=200, description="OK")
    * )
    */
   public function index() { ... }
   

5. View the docs. The package ships two UIs — hit the Redoc route (usually /opendox/redoc) for a clean read-only reference, or the SwaggerUI route (/opendox/swagger) to try requests in the browser. First use case: annotate one controller, load SwaggerUI, confirm the endpoint appears, then expand coverage controller by controller.

Implementation Patterns

• Annotation-driven, controller-first. Keep @OA\* blocks next to the methods they describe. It is the fastest way to keep docs in sync because reviewers see doc changes in the same diff as the code change.
• Separate schema classes for DTOs/models. Put @OA\Schema on dedicated classes (e.g. app/OpenApi/Schemas/User.php) instead of stuffing them into controllers. This keeps controllers readable and lets you $ref schemas from many endpoints.
• Tag per domain/version. Group operations by tag (Users, Orders, V1/Users) — SwaggerUI renders a section per tag, which is essential once you cross ~20 endpoints.
• Security schemes once. Define @OA\SecurityScheme on a single "root" annotation class (e.g. @OA\Info + @OA\Server + @OA\SecurityScheme in one file), then reference the scheme from endpoints. Don't redeclare per controller.
• Two UIs, two audiences. Redoc for stakeholder-facing "read the API" pages; SwaggerUI for engineers who want to fire requests against a dev server. Wire both in the config's servers entry so "Try it out" hits the right host.
• Generate-on-request in dev, generate-to-file for prod/CI. Cache the produced JSON artifact (the config's output path) as a build step so docs don't get rescanned on every request. Commit the JSON or publish it to a static site.
• Split docs for public vs internal APIs. Some teams define two documentation entries in config — one scanning Controllers/Api, one scanning Controllers/Admin — exposed at different route prefixes. Useful when you don't want internal endpoints leaking into a public reference.
• Contract tests. Diff generated JSON against a committed baseline in CI to catch accidental breaking changes (removed params, renamed fields). A plain git diff on the generated file is a cheap, effective gate.

Gotchas and Tips

• The package is effectively unmaintained (last release May 2021). Its tight coupling to a specific zircote/swagger-php major version will fight modern PHP/Laravel. Pin swagger-php in composer.json and expect to hold back swagger-php upgrades. If you're starting greenfield in 2024+, seriously weigh dropping straight to swagger-php + a static Redoc page instead.
• Config cache. After editing config/opendox.php, run php artisan config:clear. Stale cached config is the #1 cause of "my endpoint disappeared."
• Annotation parsing is silent on failure. A malformed @OA\* block usually just omits that operation rather than erroring. If an endpoint is missing, re-read the block for a missing closing paren/brace — swagger-php's error output is easy to miss and often buried in logs.
• Output path must be writable. If the configured JSON path isn't writable by the web user, the UI will render an empty doc with no obvious error. storage_path() under app/ is a safe target in Laravel.
• Lumen route registration order. The package registers its doc routes through the provider; if you have a catch-all route or a ->group() with a prefix that shadows /opendox/*, the UIs 404 while the JSON endpoint still works. Check php artisan route:list (Laravel) or $app->getRoutes() (Lumen).
• servers must be absolute. A relative or empty servers[].url breaks "Try it out" in SwaggerUI — it defaults to the current origin, which is usually wrong when docs are hosted separately from the API. Set the base URL explicitly per environment.
• OpenAPI 3.0 only. This targets OAS 3.0, not 3.1. Don't use type: ["string", "null"] union types or other 3.1 constructs — they'll be ignored. Use nullable: true.
• Extension points are thin. There's no plugin/event system worth using. If you need custom behavior (conditional servers per env, auth on the doc routes), wrap the package's routes with your own middleware in a service provider, or post-process the generated JSON file in a build script.
• Add auth to the doc routes in production. The UIs are public by default. Middleware the /opendox/* routes behind your standard auth guard (or disable them entirely in prod and serve the static JSON from a docs subdomain) — a live SwaggerUI in production is an accidental "try destructive endpoints" playground.