How to represent dynamic type in response body ?

[OldFarmer86]

Hello, guys! thanks for your contribution!

I am new to OpenAPI, hope you guys can help me to understand this question:

I have a legacy API like this:

POST /sea/{locator}, depends on the path parameter locator, the response body may contains objects of different types.

for example:

POST /sea/user will have response like this:

{
    "code": "200",
    "total" : 2
    "data" : [
        {
            "id" : 1
            "name": "rose"
        }
        {
            "id" : 2
            "name": "jack"
        }
    ]
}

while POST /sea/task will have response like this:

{
    "code": "200",
    "total" : 2
    "data" : [
        {
            "id" : 1
            "name": "do homework",
            "status" : "canceled"
        }
        {
            "id" : 2
            "name": "clean house",
            "status" : "finished"
        }
    ]
}

and there are many other types ...

[ralfhandl]

If you know up-front which values locator can have, and which schema corresponds to each value, then the easiest solution is to use concrete paths /sea/user, /sea/task, ... with the corresponding concrete response schema.

[handrews]

Yes, I agree with @ralfhandl . If that is not feasible, you just have to use a oneOf or anyOf schema and there's no real way to correlate the path parameter and the response type. This is something we are working to fix in OAS 4.0 a.k.a. "Moonwalk", and you can follow the discussions in the OAI/sig-moonwalk repository if you are interested.

[handrews]

I'm going to close this as answered (and addressed more deeply in the moonwalk repo)