Requests

Path parameters

Path parameters are automatically documented.

If you use model binding, Laradoc inspects the model's route key to determine the type of the parameter and generate a description. For example, for the route POST /questions/{question}/answers, the parameter will be described in the OpenAPI specifications as an integer with the description The question ID.

If you want to customize the parameter type and description, you can provide a PHPDoc comment in the controller's method. For instance:

use App\Models\Question;

class AnswerController
{
    /**
     * @param Question $question The question to answer.
     */
    public function store(Request $request, Question $question)
    {
        // ...
    }
}

Body parameters

Laradoc analyses your request validation and your controller code to identify the accepted parameters and their corresponding types.

Detection via request validation

When validating your request, Laradoc indexes the parameters and adds them to the OpenAPI specifications.

Three methods of request validation are supported:

1. Defining a rules method on a custom FormRequest class

<?php

class StoreReviewRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'rate' => ['required', 'int', 'min:1', 'max:10'],
            'comment' => ['required', 'string'],
            'photo' => ['nullable', 'image'],
        ];
    }
}

2. Invoking validate on $request or $this within the controller's method. Please note that using the request() helper is not supported yet.

public function store(Request $request, Product $product)
{
    $request->validate([
        'rate' => 'required|int|min:1|max:10',
        'comment' => 'required|string',
        'photo' => 'nullable|image',
    ]);

    // ...
}

3. Invoking make on the Validator facade, and passing the request ($request->all()) as the first argument.

public function store(Request $request, Product $product)
{
    $validator = Validator::make($request->all(), [
        'rate' => 'required|int|min:1|max:10',
        'comment' => 'required|string',
        'photo' => 'nullable|image',
    ]);

    // ...
}

Detection via request usage

Laradoc has the ability to detect request parameters through analysis of your controller, even without explicit validation of those parameters. This is achieved by indexing any usage of the following methods:

• $request->get('start_date')
• $request->input('start_date')
• $request->post('start_date')
• $request->query('start_date')
• $request->has('start_date')
• $request->whenHas('start_date', fn () => ...)
• $request->filled('start_date')
• $request->whenFilled('start_date', fn () => ...)
• $request->missing('start_date')
• $request->boolean('show_weekends')
• $request->string('name')
• $request->str('name')
• $request->integer('limit')
• $request->float('score')
• $request->date('end_date')
• $request->file('attachment')
• request('start_date')

In short, when you use any of these methods within your controller, the parameter will be added to the OpenAPI specifications.

Request examples

Laradoc makes use of the tests in your project to generate practical and accurate examples of HTTP request bodies. By automatically capturing the data transmitted in the test requests, it eliminates the need for you to take any additional steps.

This approach ensures that the examples generated by Laradoc reflect the real-world usage of your API and can be relied upon to provide a faithful representation of the request bodies that your API will accept.