PHPDoc Annotations

Document endpoints using standard PHPDoc docblock annotations.

Overview

For developers who prefer docblocks over PHP 8 attributes, Geni provides comprehensive support for standard PHPDoc annotations.

Geni supports familiar docblock conventions, making it easy to migrate from other tools:

/**
 * 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

• Summary & Description: The first line of the docblock is treated as the summary. Subsequent lines before tags are treated as the long description.
• @tags TagName, AnotherTag: Assigns operations to OpenAPI tags.
• @operationId customOperationId: Explicitly assigns an operationId.
• @deprecated: Marks the operation as deprecated.
• @unauthenticated: Omits security requirements for this specific endpoint.

Parameters

• @queryParam name type Description: Documents a query parameter.
• @pathParam name type Description: Documents a path parameter.
• @headerParam name type Description: Documents a request header parameter.

Responses

• @response status Type: Documents a response status and schema type.
  • @response 200 ArticleResource
  • @response 200 ArticleResource[]
  • @response 201 {"id": 1, "status": "created"}
  • @response 204 No Content
• @throws ExceptionClass: Automatically infers error status codes from exception types (e.g. ModelNotFoundException maps to 404).

Precedence Rules

When both inferred data and explicit annotations are present, Geni applies the following priority order:

1. PHP 8 Attributes: Highest priority. Overrides all other sources.
2. PHPDoc Annotations: Second priority. Overrides inferred data.
3. Static Inference: Lowest priority. Used when no explicit annotations are provided.