如何使用API​​ Blueprint添加值描述？

Question

有没有办法在URI参数的可能值中添加描述？

## Search Items [/items{?s}]
### Get items [GET]

+ Parameters
    + s (optional, values) ... Sort results by 
        + Values
            + `1 - price`
            + `4 - date`

如果我使用上面给出的方法，那么我就无法定义example和default值（例如，4），因为它需要完整的值（{{1 }}）。

Answer 1

否，目前无法为URI参数的可能值添加说明。

无论

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

或

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

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

使用表格

当遇到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`