Optional query parameters (with default value) with compojure-api

Question

What is the proper way to declare an optional query parameter, with default value, when using compojure-api?

One of my route elements is as follows (after reading this):

(GET "/:id/descendants" [id]
     :return [d/CategoryTreeElement]
     :path-params [id :- Long]
     :query-params [context-type :- d/ContextType
                    levels :- Integer
                    {tenant :- d/Tenant :DEF_TENANT}
                    {show-future :- Boolean false}
                    {show-expired :- Boolean false}
                    {show-suppressed :- Boolean false}
     :summary "Fetch category descendants"
     (ok ...))

At first the boolean params where defined as the other ones (e.g. show-future Boolean) but the generated Swagger UI presented them as a combobox with true value as default. In the present form the UI shows a combobox with no option selected. The same happens with tenant.

One side question: when I use Swagger generated UI to send a request and error is returned: "levels": "(not (instance? java.lang.Integer \"2\"))". Why is that? Isn't the library supposed to coerce/convert string values to the designated types declared by the API?

Thanks in advance.

Answer 1

For your first issue, this is working as designed. When you had your boolean query param required, Swagger rendered the UI which forces you to choose a value (either true or false, it just happens that it displays true on the first place).

When you changed the boolean query param to be optional, then the first empty value means "don't send this query param at all" and when you don't change it to true or false it won't append this query param to the request.

Regarding your second issue with integer query param: by default schema's json-coercion-matcher specifies String->Long coercion but not String->Integer so there is no support for Integer out of the box. You can specify your own coercer globally for your API or per route by using :coercion option (there is an example in compojure-api test). You could provide your own coercer which could extend the existing json-coercion-matcher with String->Integer case.

Answer 2

If you use clojure.spec and you want as a default value false in your swagger documentation for a boolean variable you can use spec tool library and do something like :

(s/def ::show-future 
  (st/spec {:spec boolean?
            :json-schema/example false
            :json-schema/default false}))

Then, in your query params :

:query-params [{show-future :- ::show-future false}]