设置 Nelmio ApiDoc return 参数说明

Question

在控制器的 ApiDoc 上，我们指定了输出响应对象，现在我们可以看到返回的所有参数的列表。我们如何为此列表中的版本 and/or 描述字段提供值？

我已经尝试将 @ApiDoc(description="text") 添加到响应对象的参数中，但这似乎没有任何作用。

提前致谢。

Answer 1

我没有使用过 nelmioApiDoc 但查看了它的文档，在注释部分使用 description="text" 似乎是正确的。您是否尝试过清除缓存：

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

不确定是否相关。

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

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 参数都分组在 "requirements" 下。

Answer 3

我今天浏览了 ApiDocBundle，看到 Description 来自模型属性或带有 @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();
}

同样适用于控制器方法的所有注释。

设置 Nelmio ApiDoc return 参数说明

set Nelmio ApiDoc return parameter description

symfony

nelmioapidocbundle