scribe/docs/documenting-endpoint-body-parameters.md

Documenting parameters for an endpoint

[IN PROGRESS]

Specifying request parameters

To specify a list of valid parameters your API route accepts, use the @urlParam, @bodyParam and @queryParam annotations.

• The @urlParam annotation is used for describing parameters in your URl. For instance, in a Laravel route with this URL: "/post/{id}/{lang?}", you would use this annotation to describe the id and lang parameters. It takes the name of the parameter, an optional "required" label, and then its description.
• The @queryParam annotation takes the name of the parameter, an optional "required" label, and then its description.
• The @bodyParam annotation takes the name of the parameter, its type, an optional "required" label, and then its description.

Examples:

/**
 * @urlParam id required The ID of the post.
 * @urlParam lang The language.
 * @bodyParam user_id int required The id of the user. Example: 9
 * @bodyParam room_id string The id of the room.
 * @bodyParam forever boolean Whether to ban the user forever. Example: false
 * @bodyParam another_one number Just need something here.
 * @bodyParam yet_another_param object required Some object params.
 * @bodyParam yet_another_param.name string required Subkey in the object param.
 * @bodyParam even_more_param array Some array params.
 * @bodyParam even_more_param.* float Subkey in the array param.
 * @bodyParam book.name string
 * @bodyParam book.author_id integer
 * @bodyParam book[pages_count] integer
 * @bodyParam ids.* integer
 * @bodyParam users.*.first_name string The first name of the user. Example: John
 * @bodyParam users.*.last_name string The last name of the user. Example: Doe
 */
public function createPost()
{
    // ...
}

/**
 * @queryParam sort Field to sort by
 * @queryParam page The page number to return
 * @queryParam fields required The fields to include
 */
public function listPosts()
{
    // ...
}

They will be included in the generated documentation text and example requests.

Result:

Example parameters

For each parameter in your request, this package will generate a random value to be used in the example requests. If you'd like to specify an example value, you can do so by adding Example: your-example to the end of your description. For instance:

    /**
     * @queryParam location_id required The id of the location.
     * @queryParam user_id required The id of the user. Example: me
     * @queryParam page required The page number. Example: 4
     * @bodyParam user_id int required The id of the user. Example: 9
     * @bodyParam room_id string The id of the room.
     * @bodyParam forever boolean Whether to ban the user forever. Example: false
     */

You can also exclude a particular parameter from the generated examples (for all languages) by annotating it with No-example. For instance:

    /**
    * @queryParam location_id required The id of the location. Example: 1
    * @queryParam user_id required The id of the user. No-example
    * @queryParam page required The page number. Example: 4
    */

Outputs:

curl -X GET -G "https://example.com/api?location_id=1&page=4"

Note: You can also add the @queryParam and @bodyParam annotations to a \Illuminate\Foundation\Http\FormRequest subclass instead, if you are using one in your controller method

/**
 * @queryParam user_id required The id of the user. Example: me
 * @bodyParam title string required The title of the post.
 * @bodyParam body string required The content of the post.
 * @bodyParam type string The type of post to create. Defaults to 'textophonious'.
 * @bodyParam author_id int the ID of the author. Example: 2
 * @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
 */
class MyRequest extends \Illuminate\Foundation\Http\FormRequest
{

}

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