Laravel-apidoc-generator: How to document queryParam e.g. filter[id]

[tecbeast42]

I use a filter pages which requires me to define filter params like.

filter[id]

This seems to break doc generation. Both languages bash and javascript field to compile with v3.17.1 of laravel-apidoc-generator.

This happends because the cleanQueryParameters are of the route is broken during the markdown generation step.

array:1 [
  "filter" => array:1 [
    "id" => "sint"
  ]
]

this should be

array:1 [
  "filter[id]" => "factoryValue"
]

I tracked it down to Mpociot\ApiDoc\Tools\Generator::generateConcreteSampleForArrayKeys. If i comment the use of this function out markdown generates fine.

Is there a way to enable handle ?

[shalvah]

Try out the new version 4. See the migration guide.

[ncatanchin]

@shalvah I have upgraded to v4, great work!

I was not able to get query parameters as arrays working without making changes to the example-requests templates.

The below is what I did to get the bash example working - essentially, check if $value is an array, and output only the first value. Also added the square brackets - [] after the parameter name.

curl -X {{$route['methods'][0]}} \
    {{$route['methods'][0] == 'GET' ? '-G ' : ''}}"{{ rtrim($baseUrl, '/')}}/{{ ltrim($route['boundUri'], '/') }}@if(count($route['cleanQueryParameters']))?@foreach($route['cleanQueryParameters'] as $parameter => $value)
    @if (is_array($value))
        {{ urlencode($parameter) }}[]={{ urlencode($value[0]) }}@if(! $loop->last)&@endif
    @else
        {{ urlencode($parameter) }}={{ urlencode($value) }}@if(!$loop->last)&@endif
    @endif
@endforeach

The same approach seemed to work for the PHP template:

@foreach($route['cleanQueryParameters'] as $parameter => $value)
    @if (is_array($value))
            '{{$parameter}}[]' => '{{$value[0]}}',
    @else
            '{{$parameter}}' => '{{$value}}',
    @endif
@endforeach

[tecbeast42]

I tried v4.0.2 with not success. The error is still the same. Should i open a PR? What is the use of generateConcreteSampleForArrayKeys.

[chescos]

I'm experiencing the same issue (with v4).

[shalvah]

Array query parameters are notoriously difficult to get right, primarily because there's no standard for dealing with them. Changing one thing usually breaks someone else's setup, so tread carefully.

I don't totally understand your problem or solution. Please explain them again, more clearly. Does your solution handle a situation where there are multiple items in the query param array? (e.g. filter[id], filter[name])?

[lucianobargmann]

Hey Shalvah,

I got your message on the unit tests and I understand there may be side
effects.

Yes, "filter[id], filter[name]" is exactly the situation. The solution I
sent was only for bash, and should be applied to other languages, such as
Javascript, etc.

Would it be feasible to create a config/setting to enable/disable the array
handling code? I wrote the code to fall back to your original
implementation if something went wrong. I also believe there are a few more
safety checks that can be added to ensure no breaks in compatibility.

Is there a way I can help further? I may have a couple hours free if you
want a hand.

Thanks again for your work!

Em dom, 5 de jan de 2020 18:53, Shalvah [e-mail] escreveu:

Array query parameters are notoriously difficult to get right, primarily
because there's no standard for dealing with them. Changing one thing
usually breaks someone else's setup, so tread carefully.

I don't totally understand your problem or solution. Please explain them
again, more clearly. Does your solution handle a situation where there are
multiple items in the query param array? (e.g. filter[id], filter[name])?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/mpociot/laravel-apidoc-generator/issues/637?email_source=notifications&email_token=AADZB3BDRUCADGZW6LW4YPLQ4JJGBA5CNFSM4JJVZZP2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIEAPCI#issuecomment-570951561,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AADZB3FU37EAF2QBA3KQXVLQ4JJGBANCNFSM4JJVZZPQ
.

[shalvah]

i still don't understand the problem....my understanding is that the generation process converts this into

[ "filter" => [ "id" => "...", "name" => "...", ] ]

So what exactly is wrong?🤔

[chescos]

@shalvah An exception is thrown when you try to generate the documentation. That's because the "example code" generation for bash (and a few other languages) breaks when it receives the array instead of a string.

[shalvah]

I see. So, in essence, you want two changes:

"filter" => [ "id" => "...", "name" => "...", ]

should become: "filter[id]" => "...", "filter[name]" => "...",

And then the code for handling a "list" query param value ("filter[id]" => ["...", "..."]) in the template.

I understand that the second throws an exception, but why do you wish to change the first?

If we're doing this, we're going all in. No config switches.

[chescos]

@shalvah I wasn't the guy who supplied a code fix, if I see it correctly that was @ncatanchin. I just experienced the issue, so I commented to say that it still exists in v4. Your solution looks right to me though, the code examples should just display it as a regular string instead of an array (e.g "filter[key]" => "value").

[tecbeast42]

@shalvah Could you explain why this was added MpociotApiDocToolsGenerator::generateConcreteSampleForArrayKeys?

In General if you insert params that are named filter[id] e.g.

     * @queryParam filter[id]               only session with id

i can not generate the docs anymore. I would have to override the templates to generate the docs.

The rease for that is in generateConcreteSampleForArrayKeys which will parse filter[id] and transform it into an array.

[shalvah]

Fixed in #700