0

I'm fighting with an issue with Swagger and about to go crazy... It mostly works, except one parameter. Here is the situation:

My API can take some search constraints in the URL. Users can have more than one search constraint and send them as an array as a querystring (the real case is here).

I'm having an issue with this part of my Swagger Spec (and the whole thing is below)

                        {
                            "name": "constraints",
                            "in": "query",
                            "description": "Search constraints",
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/search_constraints"
                            }
                        }

So I guess I have two questions...

1) Am I trying to do something that isn't supported by Swagger (having a parameter an array of objects in the query of the URL)

2) If not, what am I doing that is wrong?

I have been testing my JSON in http://editor2.swagger.io/, and beside the error, it works, meaning I can test the call that does the search and add constraints, etc as it should. But having the error prevent me from using readme.io and other stuff...

Thanks guys!

Full JSON

{
    "swagger": "2.0",
    "info": {
        "title": "example-api",
        "version": "1.0.0"
    },
    "host": "xxx.com",
    "basePath": "/api/1.1/meta/swagger.json/api/1.1",
    "schemes": [
        "https"
    ],
    "consumes": [
        "application/json"
    ],
    "paths": {
        "/obj/pet": {
            "get": {
                "description": "Retrieve a list of things of type pet with some optional search constraints. Retreives 100 items at most at once.",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Number of items to fetch (maximum is 100)",
                        "type": "integer",
                        "format": "int32",
                        "default": 50
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "description": "Position to start from in the list",
                        "type": "integer",
                        "format": "int32",
                        "default": 0
                    },
                    {
                        "name": "sort_field",
                        "in": "query",
                        "description": "Field to sort the list on",
                        "type": "string"
                    },
                    {
                        "name": "descending",
                        "in": "query",
                        "description": "Sorting type: descending or ascending",
                        "type": "boolean"
                    },
                    {
                        "name": "constraints",
                        "in": "query",
                        "description": "Search constraints",
                        "type": "array",
                        "items": {
                            "$ref": "#/definitions/search_constraints"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Retrieved list of pets",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "results": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/pet"
                                    }
                                },
                                "cursor": {
                                    "type": "number",
                                    "format": "float",
                                    "description": "Rank of the first item in the list"
                                },
                                "count": {
                                    "type": "number",
                                    "format": "float",
                                    "description": "Number of items in the current response. It is the minimum between the actual length of the list and the sent limit (or 100 if you did not specify a limit)."
                                },
                                "remaining": {
                                    "type": "number",
                                    "format": "float",
                                    "description": "Number of remaining items after the current response. Useful to fetch more items."
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "pet": {
            "type": "object",
            "properties": {
                "Name": {
                    "type": "string",
                    "description": "'Name' field of the current Pet"
                },
                "unique ID": {
                    "type": "string",
                    "description": "'unique ID' field of the current Pet"
                }
            }
        },
        "search_constraints": {
            "type": "object",
            "properties": {
                "key": {
                    "type": "string",
                    "description": "Field to apply the search constraint on. Can be `_all` for a full-text search"
                },
                "constraint_type": {
                    "type": "string",
                    "description": "Type of constraint. Can be anything among `equals`, `not equal`, `is_empty`, `is_not_empty`, `text contains`, `not text contains`, `greater than`, `less than`, `in`, `not in`, `contains`, `not contains`, `empty`, `not empty`, `geographic_search`"
                },
                "value": {
                    "type": "string",
                    "description": "Value to compare to"
                }
            },
            "required": [
                "key",
                "constraint_type"
            ]
        }
    }
}
  • To recap the answer from the linked question: In OpenAPI/Swagger 2.0, query parameters cannot have objects. See http://swagger.io/docs/specification/describing-parameters/#query-parameters: "You can have an array, but the items must be a primitive value type. Objects are not supported." – Helen May 01 '17 at 13:41
  • Oh, I missed that. So it's not possible. is there any workaround there? The strange thing is that the editor works well with this. Or the only option (without modifying the API) is to not have that in the specs? – Emmanuel Straschnov May 01 '17 at 13:44
  • The w/a to send an object is to use POST with a request body. But it looks like the next version - 3.0 (which is in RC as of now) - will support serializing objects into query string using the [`style`](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#style-examples) keyword. We'll know more when 3.0 is out. – Helen May 01 '17 at 13:53
  • Thanks for the tip. Do we know when it's out? – Emmanuel Straschnov May 02 '17 at 12:52
  • No idea. But given that v3 is being announced on various conferences, maybe by the end of the year? That's just pure speculation though. – Helen May 02 '17 at 14:41

0 Answers0