Forum Discussion

HenrikHL's avatar
HenrikHL
Frequent Contributor
4 years ago

Swagger compliance and queryParameter-suffix-filtering (example: ?birthday:gte=...)

Hi all,

A question regarding compliance towards a Swagger Spec:

We (our company) have decided to use suffix-notation-filters on queryParameters when filtering items in a GET endpoint returning a collection (examples: >= (gte), > (gt), <= (lte) or < (lt)).

 

Use case: get all users born after or on 2000-01-01T00:00:00+00:00

 

GET /users?birthday:gte=2000-01-01T00:00:00+00:00

 

Now - how should the query parameter (birthday) be defined in SwaggerSpec in order for the input to be valid?

 

Would the following specification be ok:

 

birthday:
  in: query
  name: birthday
  description: | 
    Limit the result based on birthday. It is possible to use operators on this query parameter by suffixing birthday with a colon and an operator at the end:
    birthday:gte=2021-01-01T00:00:00+00:00
    would result in all users with birthday >= 2021-01-01T00:00:00+00:00
    
    The following operators are supported
    - :gte (>= Greater than or equal)
    ...
  schema:
    type: string
    format: date-time

 

 

What I mean here is - should the operator be part of the SwaggerSpec name?

 

If someone is passing the ?birthday:gte=... as queryParameter - this is not compliant towards the SwaggerSpec (as it requires the queryParameter to be birthday without the :gte)!

Filter
queryParameter
suffix-notation
  • HenrikHL's avatar
    HenrikHL
    Frequent Contributor
    4 years ago

    joejoyce does SwaggerHub have an official way to do this?

     

    How should the above queryParameters be defined in order to be Swagger Compliant?

    • HenrikHL's avatar
      HenrikHL
      Frequent Contributor
      4 years ago

      Hi again,

      I was just asked by my company if there were any updates on this - I was kind of hoping that you joejoyce were going to come with an official answer 😉

      So - how should I solve the fact that I want all birthdays after a specific point in time as a query parameter?

      • HKosova's avatar
        HKosova
        SmartBear Alumni (Retired)
        4 years ago

        HenrikHL there's no straighforward way to do this. You can try defining the birthday schema as an object with four properites "birthday:gt", "birthday:gte", "birthday:lt", "birthday:lte" and limit this object to at most 1 property. By default, objects in queries are serialized so that the property name become the actual parameter names, i.e.

         

        {
  "birthday:gt": "2021-06-30T20:50:27.577Z"
}

         

        will be sent as

         

        /something?birthday:gt=2021-06-30T20:50:27.577Z

         

         

        The parameter definition would look like this:

         

              parameters:
        - in: query
          name: birthday
          description: ...
          schema:
            type: object
            minProperties: 1
            maxProperties: 1
            additionalProperties: false
            properties:
              birthday:gt:
                type: string
                format: date-time
              birthday:gte:
                type: string
                format: date-time
              birthday:lt:
                type: string
                format: date-time
              birthday:lte:
                type: string
                format: date-time

         

         

        OpenAPI 3.1's new keywords patternProperties and propertyNames will make this a bit easier by supporting regexes like ^birthday:([gl]te?)$ to define the allowed property names in schemas.