How to add value description with API Blueprint?

Question

Is there any way to add a description to possible values of URI parameter?

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

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

If I use the approach given above, then I can not define example and default values (for ex., 4), since it expects the full value (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`