设置 Nelmio ApiDoc 返回参数说明

Posted 2023-02-16

【中文标题】设置 Nelmio ApiDoc 返回参数说明

【英文标题】：set Nelmio ApiDoc return parameter description

【发布时间】：2017-09-25 20:21:37

【问题描述】：

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

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

提前致谢。

【参考方案1】：

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

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

不确定是否相关。

使用了这个section describes how versioning objects，看起来你必须在你的JMSSerializerBundle 类中使用@Until("x.x.x") 和@Since("x.x")。 See this link.

【参考方案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 参数都归入“要求”下。

【参考方案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();

这同样适用于控制器方法上的所有 cmets。

【讨论】：

您知道如何将version 添加到单独的属性吗？