Annotate Your Laravel API Endpoints with PHPDoc Tags

PHPDoc annotations offer a familiar, comment-based alternative to PHP 8 attributes for documenting your Laravel API endpoints. If you prefer to keep your documentation inside docblocks rather than as code-level attributes, Geni fully supports standard PHPDoc conventions — including all tags used by Scramble, so migrating an existing Scramble-annotated codebase requires no changes to your docblocks.

Prefer PHP 8 attributes when you want compiler-enforced syntax, IDE autocompletion, and the ability to introspect annotations at runtime. Use PHPDoc tags when you want documentation that stays close to the prose description of an endpoint, or when your team has an established docblock convention already in place.

Quick Example

The example below shows a fully annotated controller method using PHPDoc tags. The first line of the docblock becomes the operation summary, and any prose before the first tag becomes the long description.

/**
 * List published articles.
 *
 * Retrieve a paginated list of published articles with author relationships.
 *
 * @tags Articles, Content
 * @operationId articles.index
 *
 * @queryParam page int The page number to fetch. Example: 1
 * @queryParam per_page int Number of items per page. Example: 15
 * @queryParam sort string Sort field and direction (-created_at).
 *
 * @response 200 AnonymousResourceCollection<ArticleResource>
 * @response 401 {"message": "Unauthenticated."}
 *
 * @unauthenticated
 */
public function index()
{
    // ...
}

Supported Tags

Operation Metadata

Control how an operation appears in the generated spec using the tags below.

Summary & Description — The first line of the docblock is the operation summary. Any prose between the summary and the first tag becomes the long description.
@tags TagName, AnotherTag — Assigns the operation to one or more OpenAPI tags.
@operationId customOperationId — Explicitly sets the operationId for the operation.
@deprecated — Marks the operation as deprecated in the OpenAPI output.
@unauthenticated — Omits the security requirement for this specific endpoint, even when global authentication is configured.

Parameters

Document query parameters, path parameters, and request headers directly in the docblock.

@queryParam name type Description — Documents a query parameter with an optional type and description.
@pathParam name type Description — Documents a path parameter with an optional type and description.
@headerParam name type Description — Documents a request header parameter.

/**
 * Show a single article.
 *
 * @pathParam article int The ID of the article. Example: 42
 * @queryParam include_comments bool Whether to include comments. Example: true
 * @headerParam X-Client-Version string Client application version. Example: 2.4.1
 */
public function show(Article $article)
{
    // ...
}

Responses

Use @response to document the HTTP status codes and schemas your endpoint can return. Geni accepts resource class names, typed arrays, inline JSON literals, or plain text descriptions.

@response 200 ArticleResource — References an API resource class as the response schema.
@response 200 ArticleResource[] — Documents a list response.
@response 201 {"id": 1, "status": "created"} — Provides an inline JSON example.
@response 204 No Content — Documents an empty response body.
@throws ExceptionClass — Automatically infers the HTTP status code from the exception type (for example, ModelNotFoundException maps to 404).

/**
 * Store a new article.
 *
 * @response 201 ArticleResource
 * @response 422 {"message": "The given data was invalid.", "errors": {}}
 * @throws ModelNotFoundException
 */
public function store(StoreArticleRequest $request)
{
    // ...
}

Precedence Rules

When both inferred data and explicit annotations are present on the same endpoint, Geni resolves conflicts using the following priority order:

Priority	Source	When it applies
1 — Highest	PHP 8 Attributes	Overrides all other sources
2	PHPDoc Annotations	Overrides statically inferred data
3 — Lowest	Static Inference	Used when no explicit annotations exist

You can mix PHP 8 attributes and PHPDoc annotations on the same endpoint. PHP 8 attributes always win when both define the same field — for example, a #[Response] attribute takes precedence over a @response tag for the same status code.

Getting Started

Core Concepts

Integrations

Annotations

Guides

Reference

Annotate Your Laravel API Endpoints with PHPDoc Tags

Quick Example

Supported Tags

Operation Metadata

Parameters

Responses

Precedence Rules

​Quick Example

​Supported Tags

​Operation Metadata

​Parameters

​Responses

​Precedence Rules

Quick Example

Supported Tags

Operation Metadata

Parameters

Responses

Precedence Rules