Swaggervel Laravel Package

Getting Started

1. Install the package (it must match your Laravel version — see Gotchas):

   composer require appointer/swaggervel
   

   The service provider is auto-discovered on Laravel 5.5+. On older 5.x, add Appointer\Swaggervel\SwaggervelServiceProvider::class to config/app.php.

2. Publish the config so you can see every knob before touching annotations:

   php artisan vendor:publish --provider="Appointer\Swaggervel\SwaggervelServiceProvider"
   

   This drops config/swaggervel.php, which controls the JSON output directory/file, the docs and UI route paths, which directories are scanned for annotations, and the behind-laravel subdirectory flag.

3. Look here first for day-to-day work: config/swaggervel.php (routes + scan paths) and the annotation namespace expected by the locked zircote/swagger-php version (@SWG\ for 2.x, @OA\ for 3.x — check composer.lock).

4. First use case — document one endpoint end to end:

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

   Then generate and view:

   php artisan swaggervel:generate
   

   Visit the UI route (default /api/docs/ui) and confirm the endpoint appears; the raw spec is at the docs route (default /api/docs).

Implementation Patterns

• Keep global metadata in one file. Put @SWG\Info, @SWG\SecurityScheme, tags, and servers in a dedicated app/Swagger.php or app/Http/Controllers/SwaggerController.php docblock rather than scattering it across controllers. It becomes the single source of truth for API title, version, and auth definitions.

• Annotate next to the action. The natural pattern is one docblock per controller method, immediately above the method, so the annotation travels with the code it describes. Use model/schema annotations in the same block for the request/response shapes.

• Route the generated pages behind middleware. The package registers routes like any other. Wrap them in auth (and throttle) in production:

  Route::middleware(['auth'])->group(function () {
      // docs + ui routes registered by the package
  });
  

  Or gate them with the behind-laravel config and a custom middleware.

• Generate in CI, not on request. Treat the JSON spec as a build artifact: run swaggervel:generate during deploy/CI, diff the output, and fail the build if it drifts from committed expectations. This surfaces accidental annotation breakage (bad docblocks, renamed controllers) before merge.

• Use it as the contract source. The generated api-docs.json is consumed by Swagger UI, but also by Postman imports, client generators, and contract tests. Point those tools at the output file rather than at a live server.

• Version your docs alongside the API. Put the spec under /api/v1/docs and /api/v2/docs by adjusting the configured routes, or run separate specs per version, so consumers aren't looking at a moving target.

• Annotate DTOs/requests, not just controllers. Where validation rules exist, mirror them in schema annotations. Anything you skip in the annotation becomes an undocumented field consumers will guess at.

Gotchas and Tips

• Archived and version-locked. Last release was 2019. It pins illuminate/* and swagger-php to versions from that era. It works on Laravel 5.x/6-ish but will conflict with modern Laravel's dependency constraints. If you're on Laravel 8+, prefer darkaonline/l5-swagger or knuckleswtf/scribe — they solve the same problem with maintained dependencies.

• Annotation namespace mismatch is the #1 silent failure. If your docblocks use @SWG\ but the locked swagger-php is 3.x (or vice versa), parsing returns nothing and you get an empty spec with no error. Confirm the namespace from composer.lock, not from tutorials.

• Empty spec = scan path problem, not annotation problem. If the UI loads but shows no endpoints, first check paths in config/swaggervel.php actually covers your controller directories, then clear config cache (php artisan config:clear). The scanner silently skips directories it can't read.

• Writing the JSON needs a writable directory. Generation writes api-docs.json into doc-dir (often storage/app/docs or public/docs). Permission errors surface as missing docs routes or a 500 on the UI route — check write access and .gitignore it appropriately.

• Cache-bust after regenerating. Swagger UI and browsers cache the JSON aggressively. Add a query-string version or hard-refresh after swaggervel:generate; a stale spec is the most common "my endpoint change didn't show" report in day-to-day use.

• Subdirectory deployments need behind-laravel. If the app runs under /app or /api, the default UI tries to fetch the spec from the domain root and fails with a 404 in the network tab. Set behind-laravel (or adjust the base path) so the UI's fetch URL resolves.

• Don't ship docs routes to production unguarded. The routes are ordinary public routes. Expose the full spec only behind auth or an internal network — the spec is a map of every parameter and endpoint for attackers.

• Keep the JSON out of version control or keep it strictly in sync. Committing a stale api-docs.json while editing annotations is a common drift source. Pick one: generate on deploy (don't commit) or generate + commit with a CI check that fails on diff.

• Extension point: the service provider is small and the routes are registered from config, so overriding the view or adding middleware around the docs routes is the cleanest customization. Avoid subclassing the generator — the upstream is unmaintained and forks diverge.