Open tim-peters opened 7 years ago
Are you just trying to document an enum? I'm having a hard time understanding what you're trying to do here.
No, I'm not. I am trying to document the ability to filter by the value of any attribute of an object.
Think of a database with cars
(object). cars
have the attributes color
, brand
, amount_of_wheels
etc. The user should be able to filter by all of those attributes with query parameters. As far as I can see the only way to document this yet is:
## Filters [/cars{?cars,brand,amount_of_wheels}]
+ Parameters
+ color: red (string)
+ Members
+ red
+ blue
+ green
+ grey
...
+ brand: mercedes (string)
+ Members
+ mercedes
+ nissan
+ citroen
...
+ amount_of_wheels: 3 (number)
...
Now try to imagine an object with up to 100 attributes and this gets really messy. I'm looking for an easier and clearer way to document those dynamic query parameters.
I am also interested in this.
Structure we are using is following users/?filter-username=!kyslik&filter-name=~tim
, note filter prefix (since using pure column name is not good, we may have column with name page
, size
and that would conflict with pagination and limit). You may see operators !
- not, ~
- like, +
- gt, -
- lt.
How would I document that?
As far as I know, there are some rare cases where it is indispensable to use query parameters where field and value are both dynamic. For example it is much simpler to filter by more than one attribute with query parameters than with a complex URL hierarchy (and/or multiple requests).
Here is an example:
Please Notice, that
brand
andcolor
could be any attributes of the cars object, whilemercedes
andred
could be any value of those attributes.Unfortunately I haven't found a way to document this with API Blueprint properly yet. There is neither anything in the documentation about dynamic query parameters nor have I found a question concerning this.
All of the following ways are invalid:
The only valid method yet is to list all possible fields as separated parameters. IMHO this isn't handy to write nor is it easy to understand for users. Does anyone have an idea on how to document this properly with API Blueprint?