API 蓝图：语义问题“未指定值”答案

【问题标题】：API Blueprint: Semantic Issue "no value(s) specified"API 蓝图：语义问题“未指定值”
【发布时间】：2017-03-16 14:27:42
【问题描述】：

在我的蓝图中，我正在定义一个数据结构并尝试像这样使用它

+ Attributes

    + error: (Error Details, required)

文档末尾的数据结构定义：

# Data Structures

## Error Details
+ code : 1234 (number, required) - see list of error codes
+ message: User not found (string, required) - a human-readable error message

生成的示例响应正文看起来与预期的一样，但 apiary.io 上的验证显示了我使用此类构造的每个地方的语义问题，说“没有指定值”。

我做错了什么还是 apiary.io 解析器有问题？

【问题讨论】：

标签： apiblueprint apiary.io

【解决方案1】：

我遇到了同样的问题，解决了

省略冒号
分离对象定义和类型（参见本例中的owner）：

公司（对象）
- 名称：公司名称（字符串）
- 所有者（OwnerResponse）（对象）

【讨论】：

【解决方案2】：

与其他当前答案类似的答案，但仍然为我解决了这个问题。

不好：

+ Attributes
    + `status`: OK
    + `data`:
        + 5 (Channeldata)
        + 7 (Channeldata)

修复：

+ Attributes
    + `status`: OK
    + `data`
        + 5 (Channeldata)
        + 7 (Channeldata)

正如其他人所指出的，在正确的位置丢失冒号可以解决问题。

【讨论】：

【解决方案3】：

属性部分也可以定义为+ Attributes <Type Definition> (specification)，因此定义+ Attributes (Error Details, required) 应该可以解决给定的语义问题。

编辑：

当未定义示例值时，您必须在属性名称及其类型之间省略冒号：

+ Attributes

    + error (Error Details, required)

之前错过了，抱歉。

【讨论】：

不幸的是，这只适用于这个非常具体的实例。例如，如果属性类型是枚举，则不是。我想避免在多个地方重复枚举定义，但指定一个示例值也会在 apiary.io 上的允许值列表中复制该值。

公司（对象）