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. 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.

回答1:

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;

/**
 * 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.

回答2:

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.

回答3:

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".

来源：https://stackoverflow.com/questions/43667939/set-nelmio-apidoc-return-parameter-description

标签

symfony

nelmioapidocbundle