PHPDoc Annotations

​

Overview

/**
 * List published articles.
 *
 * Retrieve a paginated list of published articles with their **author**.
 *
 * - Sorted by `published_at`, newest first
 * - Drafts are never included
 *
 * @tags Articles, Content
 * @operationId articles.index
 *
 * @response 200 ArticleResource
 * @throws AuthenticationException
 */
public function index()
{
    // ...
}

​

Summary and Description

• Summary: the first paragraph, with trailing periods removed. List published articles. becomes the operation summary List published articles.
• Description: everything after the first blank line.

​

Precedence

1. #[Endpoint(title: ..., description: ...)]
2. @summary tag (summary only) and @description tag (description only)
3. The PHPDoc text (first paragraph and the rest)
4. The route name (summary fallback, for example api.projects.index)

/**
 * Docblock summary.
 *
 * Docblock description.
 *
 * @description From the tag
 */
public function show() {} // summary: "Docblock summary", description: "From the tag"

​

Markdown

​

Supported Tags

​

Operation Metadata

• @tags TagName, AnotherTag: Assigns the operation to OpenAPI tags.
• @operationId customOperationId: Sets the operationId explicitly. Without it, Geni generates one; see Operation IDs.
• @summary Text: Sets the operation summary, overriding the first docblock paragraph. A trailing period is removed.
• @description Text: Sets the operation description, overriding the docblock paragraphs.
• @deprecated [message]: Marks the operation as deprecated.
• @unauthenticated: Omits security requirements for this specific endpoint.
• @ignoreParam name: Leaves a parameter out of the documentation.
• @requestMediaType type: Sets the request body media type.

​

Responses

• @response [status] Type [description]: Documents the success response. The status defaults to 200.
  • @response ArticleResource
  • @response 201 ArticleResource Article created
  Naming a resource, model or Data class produces the same wrapped, fully inferred schema as returning it (for example {data: ArticleResource}).
• @status 201 together with @body Type: An alternative way to declare the success status and type.
• @throws ExceptionClass: Adds an error response inferred from the exception type (for example ValidationException maps to 422, AuthenticationException to 401, AuthorizationException to 403, ModelNotFoundException to 404). Map your own exceptions with withExceptionResponses().

​

Precedence Rules

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.