Laravel Swagger Docs Laravel Package

Getting Started

1. Install and publish the config:

   composer require mezatsong/laravel-swagger-docs
   php artisan vendor:publish --tag="swagger-docs-config"
   

   The config controls output path, OpenAPI version, base server URL, and which directories are scanned for annotated controllers.

2. Annotate a single controller method rather than trying to document everything at once:

   #[Group('Users')]
   public function store(StoreUserRequest $request) { ... }
   

   Schema properties are derived from the FormRequest's rules(), so start with an endpoint that already has a well-typed FormRequest — that's the path of least resistance and gives you immediate feedback on how the package maps your rules.

3. Generate and inspect:

   php artisan swagger:generate
   

   Open the emitted JSON/YAML (typically under storage/ or public/) and drop it into Swagger UI or https://editor.swagger.io to validate. Don't assume the mapping is right on the first run — the whole value of this package is that the spec stays in sync with validation rules, so verify the inferred types by eye once.

First use case to target: one grouped CRUD resource with a FormRequest on store/update and a Resource/response class on show. That exercises request bodies, path params, and response schemas in one pass.

Implementation Patterns

Rule-driven schema generation. Model the API contract through validation rules, not through hand-written annotations. Use precise rules (integer, boolean, array, email, in:..., exists) so the generated types are correct, and reserve manual overrides for the cases inference can't express.

Nested array payloads. As of 2.2.2, items.*.field style rules (e.g. items.*.quantity => integer) generate a proper nested object schema with an array of objects rather than a flat/shallow structure. Keep nested rules explicit and adjacent — deep wildcard chains are where inference is most fragile, so test these endpoints first after any upgrade.

Type accuracy for booleans and ints. 2.2.2 fixes boolean rule → boolean type generation and integer column types (previously int columns could fall through to a less accurate type). If you have request/response schemas built from model columns or casts, regenerate and diff the output — your spec will legitimately change, and front-end codegen consumers will see true/false where they may have had 0/1 or strings.

Grouping and organisation. Group by resource (#[Group('Users')] on the controller) so tags stay stable, and keep one attribute block per action. Stable operation IDs matter more than pretty summaries if you generate client SDKs.

CI drift checks. Add a step that runs php artisan swagger:generate --no-interaction and fails if the committed spec differs (git diff --exit-code on the output file). This turns documentation into a tested artifact and catches the common failure mode of someone adding a validation rule without regenerating.

Validate the artifact, not the annotations. Add one test that parses the generated JSON and asserts openapi, paths, and required components exist — or run a spec linter. This catches structural regressions that unit tests on controllers won't.

Gotchas and Tips

• Regeneration overwrites manual edits. Treat the output as build artifact. If you need permanent customisation, prefer schema/attribute extension points over editing the generated file.
• Unrecognised rules silently degrade to string. Anything the mapper doesn't understand (Rule::unique, Rule::when, complex closures, password rulesets) will lose specificity without erroring. Spot-check generated properties after adding exotic rules.
• FormRequests are resolved out of request context. Rules that depend on the current user, route model binding, or $this->route(...) can throw or produce empty enums during generation. Guard these or keep them in withValidator/conditional rules.
• Upgrade note for 2.2.x → 2.2.2. The int-column, boolean, and nested-array fixes are behaviour changes in output even though the API is unchanged. Expect a non-empty spec diff; review it before committing, and be aware that previously-worked-around schemas (hand-patched booleans, flat arrays) may now duplicate or conflict.
• Config caching in CI/deploy. If you cache config, make sure the package config is loaded before generation; a stale cached config with a different output path is a common "why is nothing generated" cause.
• Nullable/sometimes/required semantics don't map 1:1 to OpenAPI required. Verify that nullable conditions and implicit optionality came out as intended, particularly for nested array elements where only some keys are required.
• Extend rather than fork. If a rule maps wrong, register a custom type mapper or subclass the relevant attribute/schema class — these are the package's natural extension points and survive upgrades far better than patching vendor code.
• Debugging loop: reduce to a minimal FormRequest with two or three rules, regenerate, and inspect the raw JSON before blaming your annotations. The gap is almost always rule inference, not the controller attribute.