apiblueprint - 如何使用 API 蓝图添加值描述？

Question

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

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

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

如果我使用上面给出的方法，那么我不能定义example和default值（例如，4），因为它需要完整的值（4 - date）。

Answer 1

No, there is currently no way to add description to possible values of URI parameters.

Neither

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

or

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

will work correctly. I filed a feature request under API Blueprint's repository. If you want to be part of the design process and help us to get the best solution to your problem, you can track it and comment under it.

Using tables

When in troubles with API Blueprint, you can always use plain old Markdown in endpoint's description to supplement or substitute what's missing. E.g. you can freely use tables as an addition or replacement to the Values section:

# 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`