ENUM for $expand, $select, and $orderby is too restrictive

[snebjorn]

According to OAS 3

Enums You can use the enum keyword to specify possible values of a request parameter or a model property.

I believe possible values means that the ENUM values are the only valid values.

Currently this schema is generated for $expand, $select, and $orderby

{
  "schema": {
    "type": "array",
    "uniqueItems": true,
    "items": {
      "type": "string",
      "enum": ["foo", "bar", "baz"]
    }
  }
}

I like to suggest this instead

{
  "schema": {
    "type": "array",
    "uniqueItems": true,
    "items": {
      "anyOf": [
        {
          "type": "string",
          "enum": ["foo", "bar", "baz"]
        },
        {
          "type": "string"
        }
      ]
    }
  }
}

This would allow tooling to suggest values while also accepting free form text. I didn't reason about if using oneOf is more correct then anyOf.

[ralfhandl]

@snebjorn you are essential correct.

However the purpose of OpenAPI descriptions for OData services is to give a gentle introduction into some of the most prominent features and an easy "Try it out" experience in Swagger UI. They in no way describe the full set of possible requests. For example direct access to properties such as Employees/1234567/lastName is allowed and supported by many OData service frameworks out-of-the-box, and is not mentioned in the OpenAPI descriptions because it would make them unreadably long and cluttered.

For me the benchmark is "does it look nice in Swagger UI", and with the above anyOf construct - while semantically correct - it does no longer look nice in Swagger UI, which then completely ignores the enum values.

So I accept the incompleteness of the current enum construct and prefer the clickable multi-select list demonstrating the most basic features of $select and $expand.

[snebjorn]

So that's a yes if I open a PR on swagger-ui and fix the anyOf UI 🎉 - challenge accepted 😄

Update: Seems something is coming down the pipe: swagger-api/swagger-ui#3803