Query parameter examples in workbench 0.8.24


#1

After updating to workbench 0.8.24 I am getting errors in my queryParameter examples. Input:

  queryParameters:
      sort?:
        type: string[]
        description: |
          The sort order in the format `property,property[,asc|desc]`. The default sort direction is ascending.
          Can be used multiple times for different properties.
        example: ?sort=givenName&sort=surname,asc

now says “array is expected” on the example line. Changing the example to an array is certainly doable, but I think having the example that way is a serious disconnect between the documentation and reality: it may not be obvious to a human API reader that the value cannot be passed that way in the actual query string.


#2

The API Workbench is certainly right here as well as the parser since you declare a type in this context. It’s hard to differentiate between a type that is declared for query parameters and one that is a normal type. What if you want to reuse a global type in query parameters and bodies?

I agree that inside your RAML file that might not be convenient, but there are two possibilities 1) it might be up to the documentation tool that understands and renders a RAML file to display it correctly, or 2) what you might want to do (using RC2 which will be fully implemented inside the parser soon) is to disable validation for that specific example so that your example is “valid”. I certainly favour the second.

queryParameters:
      sort?:
        type: string[]
        description: |
          The sort order in the format `property,property[,asc|desc]`. The default sort direction is ascending.
          Can be used multiple times for different properties.
        example:
          strict: false # disables validation for that example
          value: ?sort=givenName&sort=surname,asc

#3

I agree that the parser is right about the type (and about being able to share types between query parameters and bodies). However, the representation of a given type is (normally) different when used within a body and when used as a query parameter (unless one is doing something silly like stuffing JSON into the URL, but in that case the value is just a string).

Shouldn’t RAML (and the parser) be aware of this distinction? As far as I can tell, it only affects example, so perhaps simply being able to disable validation for examples would be an ok solution.


#4

Trust me that is more common than you might think :smiley: