Установить описание возвращаемого параметра Nelmio ApiDoc

Question

В ApiDoc для нашего контроллера мы указали объект выходного ответа и теперь видим список всех возвращаемых параметров. Как мы предоставляем значения для полей версии и / или описания в этом списке?

Я пробовал добавлять @ApiDoc(description="text") к параметрам объекта ответа, но это, похоже, ничего не делает.

Заранее спасибо.

Answer 1

Сегодня я прошел через ApiDocBundle и увидел, что описание происходит из комментария к свойству или методу модели с @VirtualProperty.

Например:

/**
 * 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();
}

То же самое относится ко всем комментариям к методу контроллера.

Answer 2

Это рабочий метод API из одного из моих проектов:

/**
     * 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)
    {
        //...
    }

Все возвращаемые параметры APIDoc сгруппированы по "требованиям".

Answer 3

Я не использовал nelmioApiDoc, но просматривал документацию по нему, используя description="text" в разделе аннотаций кажется правильным. Вы пытались очистить свой кеш:

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

Не уверен, если это связано.

Этот раздел описывает, как используются объекты управления версиями, и выглядит так, как будто вы должны использовать @Until("x.x.x") а также @Since("x.x") в ваших классах JMSSerializerBundle. Смотрите эту ссылку.