Describe response using API Resource

[pleaz]

When API Resource exists to use it to generate a response.

[mtrajano]

That is a great idea, I had this in my TODO list. I'll hopefully get to this soon

[sanasol]

@mtrajano Proof Of Concept with shitty code :D

https://github.com/sanasol/laravel-swagger/pull/1

Problems

1. How to get any model with filled data
2. Have no idea how to fill any resource with full data
3. Have no idea how to correctly extract that structure from resource
4. Need deep definition extraction/creation to avoid duplication and creating subresource definitions.
5. Controller methods can return collection/single resource or even some custom response that contain resource deeply.

[mtrajano]

@sanasol thank you so much for submitting a pr for this. I need to think about this one a little more. I'm usually hesitant to include another annotation unless necessary (less bootstrapping needed to get the correct output), do you think it would be possible to rely on the return typehint of a specific Api Resource and leave the @model as is which would instruct which model should be passed into the resource? Also would appreciate some tests at least proving that the implementation works. I'm currently working on cleaning up this branch and trying to add as much test coverage as possible in order to do a more stable release. Thanks!

[sanasol]

This is very PoC, so it wont work anywhere except my environment. I tried replace @model with resource until found that need both for make it work somehow. So with clean implementation it should some kind of @resource + @model. But now I found out that attaching to resource also is bit useless, since response can be actually with any structure incuding some simple array.

So my current thoughts that need some custom response classes with full response structure written in annotation. i.e. empty classes with response structure and data types.

i.e. it will be just php-written swagger structure with autogeneration or something like. I didnt see any other possible solutions that will generate swagger with reallife responses automatically.

So in my mind now:

Controller method annotation

/**
* @response App\Responses\ResumeResponse
*/

Response class that linked to some "sub responses"

namespace App\Responses;

class ResumeResponse
{
    public static function generate()
    {
        return [
            'id' => 'number',
            'name' => 'string',
            'experience' => [App\Responses\ExperienceResponse::class], // collection
            'common_skill' => App\Responses\CommonSkillResponse::class, // single object
        ];
    }
}

so ExperienceResponse and CommonSkillResponse have same generate() method inside with some structure.

Actually this is very close to writing full docs manually, but with php syntax.

[mr-feek]

I started prototyping a solution for this involving traversing the AST -- https://github.com/mr-feek/laravel-swagger/commit/8f3bbad0f78d42cd3692a53a421abefe478fc05f