如何将描述添加到查询属性的“值”

Question

apiary向我展示了如何向参数添加说明。但是，我需要的是对价值进行描述。

例如/ users {？skills}。我有自己的技能代码

＆＃39; 1＆＃39;意思是说英语

＆＃39; 2＆＃39;意思是游泳

＆＃39; 3＆＃39;意味着可以开车

在参数描述之后添加它们是这样做的。如果我有技能代码的音调怎么办？而这种方法的格式很难看。我怎样才能实现它？

Answer 1

目前无法通过使用API​​ Blueprint的标准工具来实现它。

无论

+ Values
    + `A - means something`
    + `B`
    + `C`

或

+ Values
    + `A` means something
    + `B`
    + `C`

将正常工作。我在API Blueprint的存储库下提交了feature request。如果您想参与设计过程并帮助我们为您的问题找到最佳解决方案，您可以跟踪它并在其下发表评论。

外观

据我所知，在标准文档中渲染此功能并不是很好。

然而，在“beta新文档”中，它看起来好多了。尝试一下 - 在设置中，打开以下开关：

然后渲染应该看起来像这样（两个状态）：

使用表格

当遇到API蓝图的问题时，您总是可以在端点的描述中使用普通的旧Markdown来补充或替换缺少的内容。例如。您可以自由使用表作为Values部分的补充或替换：

# My API

## Sample [/endpoint{?id}]

Description.

| Value        | Meaning          |
| ------------ |:----------------:|
| A            | Alaska           |
| B            | Bali             |
| C            | Czech Republic   |

+ Parameters

    + id (string)

        Description...

        | Value        | Meaning          |
        | ------------ |:----------------:|
        | A            | Alaska           |
        | B            | Bali             |
        | C            | Czech Republic   |

        Description...

        + Values
            + `A`
            + `B`
            + `C`

在新旧文档中呈现表格：