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 <notifications@github.com> 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 <#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:

    "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 Mpociot\ApiDoc\Tools\Generator::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