apiary shows me how to add descriptions to the parameter. However, what I need is having descriptions on the value.
For example /users{?skills}. I have my own skill codes for this parameter
'1' means can speak English
'2' means can swim
'3' means can drive
Adding them after the parameter description is way to do it. What if I have tones of skill codes? And the formatting of this approach is ugly. How can i achieve it?
There is currently no way to achieve it by using standard instruments of API Blueprint.
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.
I understand that rendering of this feature isn't very nice in standard docs.
However, in "beta new docs", it looks much better. Try it out - in settings, turn on following switch:
Then the rendering should look like this (two states):
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`
Rendering of tables in old and new docs:
