nextcloud / openapi-extractor

A tool for extracting OpenAPI specifications from Nextcloud source code
https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-openapi.html
GNU Affero General Public License v3.0
6 stars 2 forks source link

fix(OpenApiType): Use anyOf instead of oneOf for conflicting types #118

Closed provokateurin closed 5 months ago

provokateurin commented 5 months ago

The current assumption that a union type is equivalent to oneOf is not correct.

The PHP type annotation

array{a: string}|array{a: string, b: int}

would mean the JSON would always be either

{"a": ""}

or

{"a": "", "b": 0}

The OpenAPI spec mandates that exactly ONE schema matches the data. No more no less. Our generated spec would look like

{
  "oneOf": [
    {
      "type": "object"
      "properties": {
        "a": {
          "type": "string"
        }
      }
    },
    {
      "type": "object"
      "properties": {
        "a": {
          "type": "string"
        }
        "b": {
          "type": "integer"
        }
      }
    }
  ]
}

The first schema would always match both possibilities (additional properties are always allowed and ignored), so the assumption that only one schema ever matches is not true.

We don't want to use anyOf all the time though, because it makes some cases harder e.g. when you have string|int because here the assumption is correct.