0

I am confused about how the end result of an URL looks like when using array- and object query parameters in OpenAPI specifications. I read the following documentation, but it did not make me understand it fully: https://swagger.io/docs/specification/describing-parameters/#query-parameters

What would be two examples of URLs based on (specifically) the below query parameters?

Example 1 - Arrays

{
"/pet/findByStatus": {
    "get": {
        "parameters": [{
            "in": "query",
            "name": "test",
            "description": "Pet object that needs to be added to the store",
            "schema": {
                "type": "array",
                "items": {
                    "properties": {
                        "id": {
                            "type": "integer",
                            "format": "int64"
                        },
                        "category": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "name": {
                                    "type": "string"
                                }
                            }
                        },
                        "name": {
                            "type": "string",
                            "example": "doggie"
                        },
                        "photoUrls": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        },
                        "tags": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "type": "integer",
                                        "format": "int64"
                                    },
                                    "name": {
                                        "type": "string"
                                    }
                                }
                            }
                        },
                        "status": {
                            "type": "string",
                            "description": "pet status in the store",
                            "enum": ["available", "pending", "sold"]
                        }
                    }
                }
            }
        }]
    }
}

Example 2 - Objects

{
"/pet/findByStatus": {
    "get": {
        "parameters": [{
            "in": "query",
            "name": "test",
            "description": "Pet object that needs to be added to the store",
            "schema": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "category": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer",
                                "format": "int64"
                            },
                            "name": {
                                "type": "string"
                            }
                        }
                    },
                    "name": {
                        "type": "string",
                        "example": "doggie"
                    },
                    "photoUrls": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "tags": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "name": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "status": {
                        "type": "string",
                        "description": "pet status in the store",
                        "enum": ["available", "pending", "sold"]
                    }
                }
            }
        }]
    }
}

Thanks!

robtot
  • 863
  • 1
  • 9
  • 31
  • The serialization behavior is not defined for nested structured like that. See the [linked Q&A](https://stackoverflow.com/q/67745944/113116) for details. If you are designing a new API (rather than documenting an exiting API), consider sending nested structures in the request body instead. – Helen Aug 10 '21 at 22:13
  • Hi! You are saying that the above example is not a valid structure for a query parameter definition? – robtot Aug 11 '21 at 05:21
  • 1
    Yes, it would result in undefined behavior. – Helen Aug 11 '21 at 06:37
  • @Helen That means their OpenAPI 3 example in this article is invalid as it also has similiar structure to my Example 2: schema: type: object properties: type: type: "string" color: type: "string" Article link: https://www.baeldung.com/openapi-json-query-parameters – robtot Aug 11 '21 at 07:22
  • That particular example is OK because it's a simple object with primitive properties. Such objects are supported and are serialized according to the defined [serialization method](https://swagger.io/docs/specification/serialization/). Only nested structures - arrays of objects, nested arrays, objects containing other objects, objects containing arrays - are not supported at this time. – Helen Aug 11 '21 at 07:31

0 Answers0