Supported annotations
Format​
Annotations in docblocks typically consist of a tag (@-something
) followed by text in a certain format. Some important details:
- The
@hideFromAPIDocumentation
,@authenticated
and@unauthenticated
tags are the only boolean tags; they don't take any text after them. - In the "Format" sections below,
?
indicates an optional value. - Most annotations are written in a "natural" format,
@tag value1 value2
, where Scribe figures out what value1 and value2 represent, based on the order. However, some tags also support attributes (@tag key1=value1 value2
or@tag value2 key1=value1
).
Attributes don't have to follow a specific order; they can be at the start or end of the tag (but they generally cannot be in the middle). Attribute values which consist of multiple words should use quotes (eg @tag key1="this is value1" value2
).
Here's a list of all the docblock annotations Scribe supports.
Metadata annotations​
tip
All metadata annotations can be used on the method or class docblock. Using them on the class will make them apply to all endpoints in that class.
Tag | Description | Format |
---|---|---|
@hideFromAPIDocumentation | Excludes an endpoint from the docs | @hideFromAPIDocumentation |
@group | Adds an endpoint to a group | @group <groupName> Example: @group User management |
@authenticated | Indicates that an endpoint needs auth | @authenticated |
@unauthenticated | Opposite of @authenticated | @unauthenticated |
Request parameter annotations​
@header
​
Describes a request header.
Format: @header <name> <example?>
Examples:
@header Api-Version
@header Content-Type application/xml
@urlParam
​
Describes a URL parameter.
Format: @urlParam <name> <type?> required? <description?> Example: <example?>
Notes:
- If you don't supply a
type
,string
is assumed. - Ending with
No-example
will prevent Scribe from including this parameter in example requests.
Examples:
@urlParam id int
@urlParam id int required
@urlParam id int The user's ID.
@urlParam id int The user's ID. Example: 88683
@urlParam id int Example: 88683
@urlParam id int required The user's ID. Example: 88683
@urlParam id int The user's ID. No-example
@queryParam
​
Describes a query parameter.
Format: @queryParam <name> <type?> required? <description?> Example: <example?>
Notes:
- If you don't supply a
type
,string
is assumed. - Ending with
No-example
will prevent Scribe from including this parameter in example requests.
Examples:
@queryParam page int
@queryParam page int The page number.
@queryParam page int required The page number. Example: 4
@queryParam page int The page number. No-example
@bodyParam
​
Describes a body parameter.
Format: @bodyParam <name> <type> required? <description?> Example: <example?>
Notes:
- Ending with
No-example
will prevent Scribe from including this parameter in example requests.
Examples:
@bodyParam room_id string
@bodyParam room_id string required The room ID.
@bodyParam room_id string The room ID. Example: r98639bgh3
@bodyParam room_id string Example: r98639bgh3
// Objects and arrays
@bodyParam user object required The user data
@bodyParam user.name string required The user's name.
@bodyParam user.age int Example: 1000
@bodyParam people object[] required List of people
@bodyParam people[].name string Example: Deadpool
// If your entire request body is an array
@bodyParam [] object[] required List of things to do
@bodyParam [].name string Name of the thing. Example: Cook
Response annotations​
@response
​
Describes an example response.
Format: @response <status?> <response>
Notes:
- If you don't specify a status, Scribe will assume
200
. - Supported attributes:
scenario
,status
Examples:
@response {"a": "b"}
@response 201 {"a": "b"}
@response 201 {"a": "b"} scenario="Operation successful"
@response status=201 scenario="Operation successful" {"a": "b"}
@response scenario=Success {"a": "b"}
@response 201 scenario="Operation successful" {"a": "b"}
@responseFile
​
Describes the path to a file containing an example response. The path can be absolute, relative to your project directory, or relative to your Laravel storage directory.
Format: @responseFile <status?> <filePath>
Notes:
- If you don't specify a status, Scribe will assume
200
. - Supported attributes:
scenario
,status
Examples:
@responseFile /an/absolute/path
@responseFile 400 relative/path/from/your/project/root
@responseFile status=400 scenario="Failed" path/from/your/laravel/3.x/storage/directory
@responseFile 400 scenario="Failed" path/from/your/laravel/3.x/storage/directory
@responseField
​
Describes a field in the response.
Format: @responseField <name> <type?> <description?>
Notes:
- You can omit the
type
; Scribe will try to figure it out from your example responses. - Can be used on controller methods and (since v3.36.0) Eloquent API resource
toArray()
methods.
Examples:
@responseField total The total number of results.
@responseField total int The total number of results.
@apiResource
​
Tells Scribe how to generate a response using an Eloquent API resource. Must be used together with @apiResourceModel
.
Format: @apiResource <status?> <resourceClass>
Notes:
- If you don't specify a status, Scribe will assume
200
.
Examples:
@apiResource App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User
@apiResource 201 App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User
@apiResourceCollection
​
Tells Scribe how to generate a response using an Eloquent API resource collection. Must be used together with @apiResourceModel
.
Format: @apiResourceCollection <status?> <resourceClass>
Notes:
- If you don't specify a status, Scribe will assume
200
.
Examples:
@apiResourceCollection App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User
@apiResourceCollection App\Http\Resources\UserApiResourceCollection
@apiResourceModel App\Models\User
@apiResourceCollection 201 App\Http\Resources\UserApiResourceCollection
@apiResourceModel App\Models\User
@apiResourceModel
​
Tells Scribe the model to use when generating the Eloquent API resource response. Must be used together with @apiResource
or @apiResourceCollection
.
Format: @apiResourceModel <modelClass>
Notes:
- Supported attributes:
states
: Comma-separated list of states to be applied when creating an example model via factory.with
: Comma-separated list of relations to be loaded with the model. Works for factory (Laravel 8+) or database fetching.paginate
: The number of items per page (when generating a collection). To use simple pagination instead, add,simple
after the number.
@apiResource App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User
@apiResourceCollection App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User states=editor,verified
@apiResource App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User with=accounts,pets
@apiResourceCollection App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User paginate=5
@apiResourceCollection App\Http\Resources\UserApiResourceCollection
@apiResourceModel App\Models\User paginate=5,simple
@apiResource App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User with=accounts states=editor,verified
@apiResourceAdditional
​
Specifies additional metadata for an API resource. Can only be used with @apiResource
and @apiResourceCollection
. The additional metadata is specified as attributes (key-value pairs).
Format: @apiResourceAdditional <key1>=<value1> ... <keyN>=<valueN>
Notes:
- Supported formats for key-value pairs:
key=value
key="long text with spaces"
"key with spaces"="long text with spaces"
Examples:
@apiResource App\Http\Resources\UserApiResource
@apiResourceModel App\Models\User
@apiResourceAdditional result=success message="User created successfully"
@transformer
​
Tells Scribe how to generate a response using a Fractal transformer. Can be used together with @transformerModel
.
Format: @transformer <status?> <transformerClass>
Notes:
- If you don't specify a status, Scribe will assume
200
. - If you don't specify
transformerModel
, Scribe will use the first argument to your method.
Examples:
@transformer App\Transformers\UserTransformer
@transformerModel App\Models\User
@transformer 201 App\Transformers\UserTransformer
@transformerModel App\Models\User
@transformerCollection
​
Tells Scribe how to generate a response using a Fractal transformer collection. Can be used together with @transformerModel
and @transformerPaginator
.
Format: @transformerCollection <status?> <transformerClass>
Examples:
@transformerCollection App\Transformers\UserCollectionTransformer
@transformerModel App\Models\User
@transformerCollection 201 App\Transformers\UserCollectionTransformer
@transformerModel App\Models\User
@transformerModel
​
Tells Scribe the model to use when generating the Fractal transformer response. Can only be used together with @transformer
or @transformerCollection
(along with @transformerPaginator
).
Format: @transformerModel <modelClass>
Notes:
- Supported attributes:
states
: Comma-separated list of states to be applied when creating an example model via factory.with
: Comma-separated list of relations to be loaded with the model. Works for factory (Laravel 8+) or database fetching.resourceKey
: The resource key to be used during serialization.
@transformer App\Transformers\UserTransformer
@transformerModel App\Models\User
@transformerCollection App\Transformers\UserTransformer
@transformerModel App\Models\User states=editor,verified
@transformer App\Transformers\UserTransformer
@transformerModel App\Models\User with=accounts,pets
@transformerPaginator
​
Tells Scribe the paginator to use when generating the Fractal transformer response. Can only be used together with @transformerCollection
.
Format: @transformerPaginator <adapterClass> <perPage?>
Examples:
@transformerCollection App\Transformers\UserCollectionTransformer
@transformerModel App\Models\User
@transformerPaginator League\Fractal\Pagination\IlluminatePaginatorAdapter
@transformerCollection App\Transformers\UserCollectionTransformer
@transformerModel App\Models\User
@transformerPaginator League\Fractal\Pagination\IlluminatePaginatorAdapter 15