Ask a Question

How to define a query parameter without value not using allowEmptyValue?

mvalle
New Contributor

How to define a query parameter without value not using allowEmptyValue?

I have a query parameter for which only its presence is important.

For example, I have a sort parameter that if present makes the returned list sorted, otherwise the list is unsorted one. For example: https://example.com/api/documents?sort returns a sorted list of documents.

Currently I model it in OpenAPI this way:

      parameters:
        - name: sort
          in: query
          description: If present the list is sorted
          required: false
          allowEmptyValue: true
          schema:
            type: boolean
But OpenAPI specifications suggests not to use allowEmptyValue because it will be removed in a future version of the specification.
That said, which is the correct way to define this kind of query parameter?
Thanks!
mario
 
2 REPLIES 2
mhiggins
Staff

Re: How to define a query parameter without value not using allowEmptyValue?

You are right to not rely on: allowEmptyValue.

Best practice for this use case would be to use a standard name:value parameter. …/?sort=true

I have also seen this implemented as… /documents/sort (e.g. as a unique path)
——-
Micheál Higgins
Senior Solutions Architect
m: micheal.higgins@smartbear.com

HKosova
Moderator

Re: How to define a query parameter without value not using allowEmptyValue?

Related discussion in the OpenAPI Specification repository:

Not clear how to describe a “flag” parameter in OpenAPI 


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
cancel
Showing results for 
Search instead for 
Did you mean: