laravel-request-docs

laravel-request-docs copied to clipboard

Is any type of return properties list supported or we should execute an example request to be able to see the response format ? I am using ...Resource classes (something like below) to be returned from each controller method response so the returned keys could be extracted the same way as they are for Request classes:

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class ClientResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'displayName' => $this->display_name,
        ];
    }
}

Thanks I can see how this can be useful. And this should be doable although it won't work 100% all the time. For example:

We won't be able to get the exact response format from Reflection in the example below, where the user uses a variable.

    public function toArray($request): array
    {
       $response = [
            'id' => $this->id,
            'displayName' => $this->display_name,
        ];
        return $response
    }

We can still create an obj on reflection class and mock the $this method to obtain the response of the array, but still, some users may have some code that may throw errors such as below:

    public function toArray($request): array
    {
       $response = [
            'username' => Auth::user()->username,//<--- example this will throw an error upon Reflection
            'displayName' => $this->display_name,
        ];
        return $response
    }

Got it. Maybe a solution would be to parse the file without PHP interpreter and extract the keys of the ->toArray method. This means the response type will not have example values but at least a list of possible keys would be displayed in the documentation.

Parsing by regexp is not as simple as it sounds. We tried it as a fallback strategy for the rules here https://github.com/rakutentech/laravel-request-docs/blob/master/src/LaravelRequestDocs.php#L213-L245

The accuracy really depends on how code is written, for example, multiline, dirty one-liners, etc. And it is not necessary that the resource file has only one array declared and we can magically get all the keys.

One solution that may work for GET requests would be making the actual API call at the time of request-docs page load to all the endpoints and then showing the sample responses.

Open to ideas and pull reqs of course.

@kevincobain2000 Hi! There are suggestions to use PHPDoc annotations and collect information on them. For example, they are used by PHPStan and psalm. They are also well known by modern IDEs. As an example:

    /**
     * @param Request $request
     * @return array{
     *     id: int,
     *     name: string,
     *     user: ProfileResource<User>
     * }
     */
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'user' => new ProfileResource($this->user)
        ];
    }

There is a great lack of documentation of the answers.

Thanks!

There are suggestions to use PHPDoc annotations and collect information on them. For example, they are used by PHPStan and psalm.

Needs to be looked into @kitloong and @kevincobain2000

@kevincobain2000 Hi! There are suggestions to use PHPDoc annotations and collect information on them. For example, they are used by PHPStan and psalm. They are also well known by modern IDEs. As an example:

    /**
     * @param Request $request
     * @return array{
     *     id: int,
     *     name: string,
     *     user: ProfileResource<User>
     * }
     */
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'user' => new ProfileResource($this->user)
        ];
    }

There is a great lack of documentation of the answers.

Thanks!

If it was difficult to parse in the programming way. Can we support "PHPDoc annotations" for responses only -> At least it covers all process of documents

Thanks for the suggestion. We can support PHPDoc annoatations.

Closing this issue, however added the link to the suggestion about PHPDoc annotations in #124