Documenting query and URL parameters for an endpoint

Attention

These docs are for Scribe v2, which is no longer maintained. See scribe.knuckles.wtf/laravel for Scribe v3.

Specifying query parameters

To describe query parameters for your endpoint, use the @queryParam annotation on the method handling it.

The @queryParam annotation takes the name of the parameter, an optional type, an optional “required” label, and a description.

If you don’t specify a type, Scribe will assume it’s string. See the documentation on body parameters for a list of valid types.

Here’s an example:

/**
  * @queryParam sort string Field to sort by. Defaults to 'id'.
  * @queryParam fields required Comma-separated list of fields to include in the response. Example: title,published_at,is_public
  * @queryParam filters[published_at] Filter by date published.
  * @queryParam filters[is_public] integer Filter by whether a post is public or not. Example: 1
 */
public function listPosts()
{
    // ...
}

The query parameters will be included in the generated documentation text and example requests:

../_images/endpoint-queryparams-1.png

../_images/endpoint-queryparams-2.png

If you need to handle array/object parameters, you can use the same conventions as for body parameters:

/**
  * @queryParam sort string Field to sort by. Defaults to 'id'.
  * @queryParam fields string[] required Comma-separated list of fields to include in the response. Example: title,published_at,is_public
  * @queryParam filters object Fields to filter by
  * @queryParam filters.published_at Filter by date published.
  * @queryParam filters.is_public integer Filter by whether a post is public or not. Example: 1
 */

../_images/endpoint-queryparams-4.png

Tip

You should avoid using query parameters that are arrays or objects, because [there isn’t a standardised format for handling them](https://stackoverflow.com/a/9547490/7370522).

If you’re using a FormRequest in your controller, you can also add the @queryParam annotation there instead, and Scribe will fetch it.

/**
 * @queryParam user_id required The id of the user.
 */
class CreatePostRequest extends \Illuminate\Foundation\Http\FormRequest
{

}

// in your controller...
public function createPost(CreatePostRequest $request)
{
    // ...
}

Specifying example values

By default, Scribe will generate a random value for each parameter, to be used in the example requests and response calls. If you’d like to use a specific example value, you can do so by adding Example: your-example-here to the end of your description.

Tip

You can exclude a particular parameter from the generated examples by ending with No-example instead. The parameter will still be included in the text of the documentation, but it won’t be included in response calls or shown in the example requests.

For instance:

    /**
     * @queryParam sort Field to sort by. Defaults to 'id'. Example: published_at
     * @queryParam fields required Comma-separated fields to include in the response. Example: title,published_at,id
     * @queryParam filters[published_at] Filter by date published. No-example
     * @queryParam filters[title] Filter by title. No-example
    */

../_images/endpoint-queryparams-4.png

Describing URL parameters

To describe parameters in the URL, use the @urlParam annotation. For instance, if you defined your Laravel route like this:

Route::get("/post/{id}/{lang?}");

you can use this annotation to describe the id and lang parameters as shown below. The annotation takes the name of the parameter, an optional type, an optional “required” label, and then its description. Like with @queryParams, a random value will be generated, but you can specify the value to be used in examples and response calls using the Example: syntax.

If you don’t specify a type, Scribe will assume it’s string. Valid types are string, integer, and number.

/**
 * @urlParam id integer required The ID of the post.
 * @urlParam lang The language. Example: en
 */
public function getPost()
{
    // ...
}

../_images/endpoint-urlparams-1.png

Note

If you want Scribe to omit an optional parameter (lang in our example) in requests and response calls, specify No-example for the parameter.

/**
 * @urlParam id required The ID of the post.
 * @urlParam lang The language. No-example
 */
public function getPost()
{
    // ...
}

../_images/endpoint-urlparams-2.png