Annotate Inspec API

Controller Rules

• Prefer summary and tags. Use tags as a string or array.
• Set responseCode explicitly for non-200 success responses, especially 201 for create endpoints.
• Use additionalResponses for route-specific extra statuses or inferred-error overrides. Values may be null, plain strings, Response instances, or Response class strings.
• Use deprecated: true for deprecated endpoints.
• Use multipart: true when the endpoint is multipart even if no field uses the file type.
• Do not rely on description yet. The attribute accepts it, but the generator does not emit it currently.
• Do not annotate helper methods that are not bound to Laravel routes. The generator skips them.

DSL Rules

• Read references/inspec-annotation-reference.md before writing non-trivial request or response bodies.
• Use name[?][!]:type[,typeArg...][|modifier:arg[,arg...]].
• Remember that ? and ! change meaning by context:
  • In request, response, and paginator meta objects, ? means optional and ! means non-nullable.
  • In route parameters, ? controls requiredness. Path parameters are usually not optional.
  • In query parameters, ! controls requiredness.
  • In transformer #[Schema(...)] objects, ? makes the field nullable; Inspec does not currently emit a required array for schema objects.
• Use array,<itemType> for primitive arrays, or use 'data:array' => UserTransformer::class for arrays of transformer-backed objects.
• Use |enum:a,b,c or |enum:App\\Enums\\BackedEnum.
• Use file for uploads; it becomes type: string with format: binary.
• When a property value is an array (inline nested object), always include '@description' => '...' as the first key to give the object a description. Do not leave nested objects without a description.

Transformer Rules

• Put #[Schema(object: [...])] on the transformer's transform() method.
• The schema name defaults to the transformer class basename without Transformer; override with name: only when needed.
• Only include* methods are considered for expands. Other methods (transform, helpers, etc.) are skipped.
• The property name is the method name in snake_case after stripping include: includeTeam() → team, includeCoAuthors() → co_authors.
• Do not define a schema array in a constant/property and reuse it in #[Schema(...)]; keep schema entries written directly in the attribute.
• Each expand is emitted as a type: object with a nested data property:
  • #[ExpandItem(Transformer::class)] — data is a $ref to the transformer schema.
  • #[ExpandItem([A::class, B::class])] — data is an allOf list of $ref entries.
  • #[ExpandCollection(Transformer::class)] — data is a type: array whose items is a $ref to the transformer schema.
• ExpandCollection only accepts a single transformer class. Use ExpandItem([...]) for multi-transformer unions.
• All referenced transformer schemas are registered as reusable #/components/schemas/ entries.

Current Behavior To Respect

• Api enables Sanctum and broadcasting integrations by default. Use withoutSanctum() or withoutBroadcasting() when the generated spec should opt out.
• With Sanctum enabled, routes using auth:sanctum automatically receive bearerAuth; do not model that in the attribute.
• With broadcasting enabled, Inspec auto-documents the registered Pusher-related broadcasting auth routes when they exist.
• withBroadcasting(fn (Operation $operation, Route $route) => ...) can customize those auto-documented broadcasting operations or return null to skip one.
• A request body automatically adds a 422 validation response unless additionalResponses[422] or API-level error-response configuration overrides it.
• Routes with throttle middleware automatically add a 429 response unless additionalResponses[429] or API-level error-response configuration overrides it.
• API-wide inferred error defaults live on Api::withValidationErrorResponse(), Api::withoutValidationErrorResponse(), Api::withTooManyRequestsResponse(), and Api::withoutTooManyRequestsResponse().
• Standard non-paginated success payloads still come from response: [...]. Use Api::withSuccessResponse() when that payload should be wrapped or when the default success description, headers, or content type should change API-wide.
• paginatedResponse and cursorPaginatedResponse currently work with transformer class strings, not inline object arrays.
• API-wide pagination defaults live on Api::withPagination() and Api::withCursorPagination().
• The paginator owns query params, paginator schema/meta, and the generated paginated success response. If the envelope needs to change, use a custom paginator subclass or reconfigure the API-level paginator definition.
• Request and response requiredness is not fully represented as OpenAPI required arrays yet, so keep the DSL truthful to app behavior but expect that limitation.
• Use Api::prefix('api') when Laravel routes live under /api but generated paths should omit that prefix.
• When an API uses prefix(...), match generated paths in --path filters, for example ^/users instead of ^/api/users.
• Verification-first command examples:
  • php artisan inspec:generate --api=App\\OpenApi\\WebhookDocumentation --stdout
  • php artisan inspec:generate --api=webhooks --stdout --path='^/webhooks' --method=POST
  • php artisan inspec:generate --api=webhooks --stdout --route=webhooks.receive
• Avoid regenerating files on disk unless the user explicitly asked for the output files to be written.

Reference

Use references/inspec-annotation-reference.md for the full #[Route] argument guide, DSL syntax, context-specific marker semantics, transformer patterns, and current caveats.