CODEWITHSUNDEEP
symfonynelmioapidocbundle
Aaron Luman
Aaron Luman

Reputation: 655

set Nelmio ApiDoc return parameter description

On the ApiDoc for our controller we have specified the output response object and now we see a list of all the parameters that get returned. Output Params How do we provide values for the version and/or description fields on this list?

I have tried adding @ApiDoc(description="text") to the response object's parameters but that doesn't seem to be doing anything.

Thanks in advance.

Upvotes: 2

Views: 2008

Answers (3)

Aaron Luman
Aaron Luman

Reputation: 655

I stepped through the ApiDocBundle today and see that Description comes from the comment on the model property or method with @VirtualProperty.

For example:

/**
 * This text will be displayed as the response property's description
 *
 * @var \DateTime
 * @JMS\Type("DateTime<'Y-m-d\TH:i:sO'>")
 */
protected $dateTimeProperty;

or 

/**
 * VirtualProperty comment
 *
 * @JMS\Type("integer")
 * @JMS\VirtualProperty()
 * @return integer
 */
public function getVirtualProperty()
{
    return $this->someFunc();
}

The same applies to the all comments on the controller method.

The result of the above ^

Upvotes: 1

Medard
Medard

Reputation: 1059

This is a working API method from one of my projects:

/**
     * Get an extended FB token given a normal access_token
     *
     * @ApiDoc(
     *  resource=true,
     *  requirements={
     *      {
     *          "name"="access_token",
     *          "dataType"="string",
     *          "description"="The FB access token",
     *          "version" = "1.0"
     *      }
     *  },
     *  views = { "facebook" }
     * )
     * @Get("/extend/token/{access_token}", name="get_extend_fb_token", options={ "method_prefix" = false }, defaults={"_format"="json"})
     */
    public function getExtendTokenAction(Request $request, $access_token)
    {
        //...
    }

All APIDoc parameters that get returned are grouped under "requirements".

Upvotes: 1

Alvin Bunk
Alvin Bunk

Reputation: 7764

I haven't used nelmioApiDoc but looking at the documentation for it, using description="text" in the annotation section seems correct. Have you tried clearing you cache:

php bin/console cache:clear --env=prod

Not sure if it is related.

This section describes how versioning objects is used, and looks like you have to use @Until("x.x.x") and @Since("x.x") in your JMSSerializerBundle classes. See this link.

Upvotes: 0

Related Questions