[ISSUE-739] ApiDoc parameters setting will override lower parameter definitions in the hierarchy

[fstr]

Patch for #739

[fstr]

I'm using the parameters setting which is read from the ApiDoc annotation and merge it in the end on top of all other parameters definitions that have been read from lower annotations in the hierarchy.

Sadly I can't prove in my test that I override an already read parameter definition, because they are empty. In my production code the JMSMetaDataParser will already fill the annotation::parameters property.

I'm not sure why they are empty in the tests. Since the handler is registered.

[willdurand]

that was fast :p

[fstr]

I already wrote it but wanted to create an issue about it first.

[willdurand]

Sadly I can't prove in my test that I override an already read parameter definition, because they are empty. In my production code the JMSMetaDataParser will already fill the annotation::parameters property.

I'm not sure why they are empty in the tests. Since the handler is registered.

arf, that's a bit sad indeed. could you look at why there is no information available from the JMSMetaDataParser?

[fstr]

The properties weren't available because of some Groups setting in the annotation.

I think in general this needs some more improvement to work with nested objects.

[fstr]

Added a new test which tests and shows how to use the properties ApiDoc setting on nested objects.
It's a bit cumbersome, but that way it is conform with the way the ApiDoc annotation is read and how it can be merged using the existing mergeParameters method.

    /**
     * @ApiDoc(
     *     output="Nelmio\ApiDocBundle\Tests\Fixtures\Model\JmsTest",
     *     input={
     *         "class" = "Nelmio\ApiDocBundle\Tests\Fixtures\Model\JmsTest"
     *     },
     *     parameters={
     *          {
     *              "name"="number",
     *              "dataType"="integer",
     *              "actualType"="string",
     *              "subType"=null,
     *              "required"=true,
     *              "description"="This is the new description",
     *              "readonly"=false,
     *              "sinceVersion"="v3.0",
     *              "untilVersion"="v4.0"
     *          },
     *          {
     *              "name"="arr",
     *              "dataType"="object (ArrayCollection)"
     *          },
     *          {
     *              "name"="nested",
     *              "dataType"="object (JmsNested)",
     *              "children": {
     *                  "bar": {
     *                      "dataType"="integer",
     *                      "format"="d+"
     *                  }
     *              }
     *          }
     *     }
     * )
     */

[willdurand]

great. if tests are all green, could you please squash your commits?

[fstr]

This patch would enable people to overwrite the parameters in the docs in their controller method ApiDoc annotation. The parameters only represent the "input".

Would it be interesting to have the same feature for the "output"?
Something like responseParameters or returnParameters, which enables users the overwrite the Return parameters that are listed in the generated API docs.

With this patch I am able to tell developers that use my API that I expect an array in my PUT request (which is internally a CustomFooCollection), but for my GET request where the developers fetch the same resource, I have no possibility to tell them I return a simple array (which is internally a CustomFooCollection) and currently represented in my Return parameter list as CustomFooCollection.

If this would be interesting for the project, I'm willing to provide a separate patch for it.

[willdurand]

Would it be interesting to have the same feature for the "output"?

I'm not sure about it. Let's postpone this idea.

[fstr]

Alright!

I squashed the commits into one feature commit.

[willdurand]

thanks!