Swagger parameter polymorphism

2
votes

It is possible to define input parameter in Swagger with multiple types?

Example: I have API that adresses resources using URL http://localhost/tasks/{taskId}. But every task contains integer id and also string uuid. I would like to allow user to address resource both by id or uuid - so both http://localhost/tasks/123 and http://localhost/tasks/51f12dbc-02e7-41a6-ab81-2381caea0176 URLs are valid.

But, regarding to the swagger documentation (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameter-object) parameter object can have only single type

Type: Required. The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of "string", "number", "integer", "boolean", "array" or "file".

So how can I describe input path parameter as string/integer?

2
javascriptnode.jsapiswagger

2 Answers

3
votes

There's no way to define a parameter belonging to multiple types in Swagger spec.

In your case, I think you can workaround using string, which can represent both string (e.g. "51f12dbc-02e7-41a6-ab81-2381caea0176") and integer (e.g. "123") in the path parameter and the server should receive the data correctly.

1
votes

This is possible in OpenAPI 3.0 using oneOf:

openapi: 3.0.0
...
paths:
  /tasks/{taskId}:
    parameters:
      - in: path
        name: taskId
        required: true
        schema:
          oneOf:
            - type: integer
              example: 123
            - type: string
              format: uuid
              example: 51f12dbc-02e7-41a6-ab81-2381caea0176