如何在 Nelmio ApiDocBundle 中指定参数的格式

Posted 2023-02-16

【中文标题】如何在 Nelmio ApiDocBundle 中指定参数的格式

【英文标题】：How specify parameter's format in Nelmio ApiDocBundle

【发布时间】：2016-01-18 06:02:14

【问题描述】：

我使用@ApiDoc 注释的input 属性来指定作为表单字段的我的api 的参数。

 * @ApiDoc(
 *      section="User",
 *      resource=true,
 *      input=
 *          "class"="Nik\UserBundle\Form\UserType",
 *      ,
 *     ....

data_class of form 是一个对属性进行约束验证的实体。

我希望 nelmio api doc 指定参数格式作为实体的验证约束，但格式为空。

如何在 nelmio ApiDocBundle 中指定参数格式？

---

编辑： 也许我写了一个不好的问题。

我们可以为input & output指定解析器，如果我们没有为这些指定解析器，它会为input和output调用所有解析器，然后为UserType调用所有解析器。

nelmio 有一个名为 ValidationParser 的解析器，它有一个名为 parseConstraint 的方法，该方法将 format 设置为输入和输出，但我的文档没有调用此方法，为什么？

【问题讨论】：

您是如何为每个字段指定 description 的？我找不到任何可靠的。

好的，我在这里找到了答案***.com/a/43810982/1335142

【参考方案1】：

格式列仅适用于datetime、date 和choice 类型。

对于datetime 和date，它表示日期格式，如Y-m-d H:i:s 和choice 的选项数组。

我没有找到任何关于它的文档，所以我不得不查看源代码。这是FormTypeParser类，FormType实际被解析的地方，你可以看到格式字段是如何设置的。

在FormTypeParserTest 类中，您可以看到如何使用它。只需为其中一种可用类型传递带有format 名称的字符串参数，解析器就会处理它。

更新：您将在 FormType 类中定义约束。

例如：

class TestType extends AbstractType

    /**
     * @Assert\Type("string")
     * @Assert\Length(min="10", max="255")
     * @Assert\Regex("/^[^<>]+$/i")
     */
    private $title;

    /**
     * @Assert\Type("string")
     * @Assert\Length(min="10", max="255")
     * @Assert\Regex("/^[^<>]+$/i")
     */
    private $content;

    /**
     * @Assert\Date()
     */
    private $created;

    public function getName()
    
        return 'test';
    

会被解析成：

ValidationParser 在 doParse() 方法查找在 FormType 类中定义的所有约束，然后为每个约束执行 parseConstraint() 方法。

如上所述，您也可以使用FormTypeParser。例如：

public function buildForm(FormBuilderInterface $builder, array $options)

    $builder->add('created', 'date', array('label' => 'Created', 'format' => 'yyyy-MM-dd'))
        ->add('color', 'choice', array('label' => 'Color', 'choices' => array('grey' => '#CCCCCC', 'red' => '#FF0000')))
        ->add('save', 'submit');

将被解析为：

希望现在有帮助！

【讨论】：

谢谢，它的工作原理，但第一种方式，我强制重新定义表单类型中的所有实体属性没有用，第二种方式，我不能将其他字段的格式指定为文本

【参考方案2】：

我提交了一个使用 format 属性的验证元数据的拉取请求。

你可以看到这个PRhere

【参考方案3】：

如您所见here，您可以在注释中指定过滤器，就像它完成的文档示例一样。

这里是这个例子的一部分：

/**
 * This is the documentation description of your method, it will appear
 * on a specific pane. It will read all the text until the first
 * annotation.
 *
 * @ApiDoc(
 *  resource=true,
 *  description="This is a description of your API method",
 *  filters=
 *      "name"="a-filter", "dataType"="integer",
 *      "name"="another-filter", "dataType"="string", "pattern"="(foo|bar) ASC|DESC"
 *  
 * )
 */
public function getAction()

【讨论】：

我不想手动编写过滤器，我将使用我的表单作为输入，而 nelmio 读取表单和实体验证并将其用作参数格式