OpenAPI 3 parameter documentation not generated for :and

[Sardtok]

With the older OpenAPI 2 support I could define parameters to have top-level validation like so:

:parameters {:query [:and [:map
                           [:x int?]
                           [:y int?]]
                     [:fn #(< (:x %) (:y %))]]}

The parameters would show up in the generated JSON and in Swagger UI. When I change to create-openapi-handler, the parameter list for the endpoint is empty.

Is this by design? Do I need to move this kind of validation out of the Malli coercion flow?

[opqdonut]

The problem is that the :query parameter schema should be a :map so that the OpenAPI generation can grab the schemas of the individual query params out of it. In the final OpenAPI spec, the :map level disappears, in a sense, and the spec only mentions the individual properties.

We should probably add a warning for the case when the OpenAPI generation fails to find the individual query params.

We could also add special case support for [:and [:map ...] [:fn ...]], but handling something like [:and [:map ...] [:map ...]] would be more tricky, so I'm hesitant to do that.

The reason this works in Swagger/OpenAPI2 is that the version of :and in Swagger, "x-allOf" is a hack, and the final schema looks more like a map schema. See below.

;; Input
[:and
 [:map [:x int?] [:y int?]]
 [:fn #(< (:x %) (:y %))]]

;; OpenAPI 2 output
{:properties {:x {:format "int64", :type "integer"}, :y {:format "int64", :type "integer"}},
 :required [:x :y],
 :type "object",
 :x-allOf [{:properties {:x {:format "int64", :type "integer"},
                         :y {:format "int64", :type "integer"}},
            :required [:x :y],
            :type "object"}
           {}]}

;; OpenAPI 3 output
{:allOf [{:properties {:x {:type "integer"}, :y {:type "integer"}},
          :required [:x :y],
          :type "object"}
         {}]}

[opqdonut]

I've added a warning for this.

[Sardtok]

I can see how supporting every possible permutation of a schema that is valid for coercion would be tricky. I would imagine [:and [:map ...] [:map ...]] would be a map union of the two maps, but I can see how collisions between keys could be a problem. During coercion, you can simply apply the rules, even if rules conflict, but generating an OpenAPI spec from such a schema wouldn't be possible.

E.g. this shouldn't be a problem:

[:and [:map [:x :int]]
      [:map [:y :int]]

But something like the following doesn't make sense, and would be impossible to generate a spec from:

[:and [:map [:x :int]]
      [:map [:x :string]]

And then there's of course a question of whether :or could be supported. I don't think we have any cases of :or for query parameter specs, but I think there are cases that could make sense, but it would be very difficult to say anything about parameters being required or not.

[opqdonut]

Yeah the core problem here is that OpenAPI wants to model each query parameter separately, so there's really no way to even express something like [:or [:map [:x :int]] [:map [:y :string]]] in OpenAPI 3. You just have to go with a more open schema like [:map [:x {:optional true} :int] [:y {:optional true} :string]].

PS. this is for query params. For body params, :or, :and, :multi etc. work perfectly!