Allow to describe parameters

[nichtich]

The description of parameters in Swagger is not very helpful, e.g.

A value of type string that will substitute ?_name in the original query

How about adding a decorator to give an optional description of parameters? So with

#+ parameters:
#+   name: name of the person

The description could be

name of the person (string)

[c-martinez]

Hi @nichtich !

Thanks for your suggestion. This would indeed be a good improvement.

I guess it would be nice if we could combine this with the defaults decorator.

#+ parameters:
#+   name: 
#+     description: name of the person
#+     default: "Bob"

Are there other properties that would be good to define for a parameter? Maybe enumerate as well?

@albertmeronyo what do you think?

[nichtich]

Adding example values would also be helfpul.

[c-martinez]

We could have something like this:

#+ parameters:
#+   name: 
#+     description: name of the person
#+     default: "Bob"
#+     enumerate: ["Alice", "Bob", "Charles"]
#+     example: "Alice"

The only thing we need to decide is if this syntax is complementary or a replacement of the current syntax for enumerate and default decorators.