PHPDoc annotations

PHP autodoc uses native PHP types and PHPDoc annotations to determine data types to show in generated documentation. If you are using a static analysis tool like PHPStan, you will find that autodoc works well without any changes to your code base.

Supported tags

@example

/**
 * @example 10.55
 */

@extends

This tag can be useful when extending a generic class. See example usage in Generic types section.

/**
 * @extends Response<null>
 */

@mixin

Use this tag to specify that some property types of this class are being delegated to another class. This tag is useful when using Laravel Eloquent API Resources and dynamically accessing the underlying Model propeties with $this->.

/**
 * @mixin User
 */

@param

/**
 * @param {type} $parameterName
 */

@phpstan-type

Visit PHPStan Local type aliases for more info.

/**
 * @phpstan-type TypeAlias {type}
 */

@phpstan-import-type

Visit PHPStan Local type aliases for more info.

/**
 * @phpstan-import-type TypeAlias from DefiningClass
 */

@property

You may specify property type using PHPDoc just above the property definition with @var, however in case you have dynamic properties, you might want to describe the properties in a PHPDoc above class definition using @property.

/**
 * @property {type} $propertyName Description of the property.
 */

@property-description

This tag can be used instead of @property when you want only to define property description without overriding data type.

/**
 * @property-description $propertyName Description of the property.
 */

@property-example

You may define property example using PHPDoc with @example just above the property definition, however in case you have dynamic properties, you may put the example in a PHPDoc above class definition using @property-example.

/**
 * @property-example $propertyName '2025-01-01'
 */

@response

This annotation can be used in a class method PHPDoc comment to indicate the response type for the method. If the @response tag is present, @return tag will be ignored. This can be useful when there are some manipulations done with the return value and the actual response body is different. If this is a common issue in your project, we recommend using custom extensions.

/**
 * @response {type}
 */

@return

/**
 * @return {type}
 */

Conditional return types are evaluated as union types in the generated documentation.

/**
 * @return (T is int ? string : array<string>)
 */

@template

See example usage in Generic types section.

/**
 * @template T
 */

/**
 * @template TClass of SomeClass
 */

@template-covariant

/**
 * @template-covariant T
 */

@template-contravariant

/**
 * @template-contravariant T
 */

@var

/**
 * @var {type}
 */

/**
 * @var {type} $varName Description of the variable.
 */

Reading descriptions

PHP autodoc reads descriptions for types from text in PHPDoc comments.

/**
 * Description of the next variable.
 */
$theNextVariable = null;

Above class methods or closures that are entrypoints for routes, the first paragraph of PHPDoc comment is parsed as title, and the rest as description. This behavior is disabled when openapi.show_routes_as_titles setting is enabled.

/**
 * Title of the operation
 * 
 * Description...
 */
public function create()