fix: update http exception's schema construction to include items key…

[nathanielarking]

An Openapi schema is generated for every HttpException passed into the raises kwargs of a route handler. The schema for the extra attribute of the HttpException currently generates this schema:

extra:
  additionalProperties: {}
  type:
    - 'null'
    - object
    - array

This schema fails to comply with two rules of the IBM openapi validator, ibm-avoid-multiple-types and ibm-array-attributes. This causes sdk generation with Orval to fail.

This PR changes the schema generation for the HttpException to generate this:

extra:
  additionalProperties: {}
  anyOf:
    - type: 'null'
    - type: object
    - items: {}
      type: array

[provinzkraut]

@nathanielarking this looks good to me but it's still in draft mode. Is there any more work you want to do here?

[provinzkraut]

@nathanielarking It seems like our TypeScript generation assumes the faulty schema this PR fixes. Do you feel comfortable fixing this as well?

Additionally, after consulting the OA 3 spec, it seems that a list of types is actually disallowed in general:

type takes a single value. type as a list is not valid in OpenAPI

https://swagger.io/docs/specification/data-models/data-types/

Maybe we should disallow passing a list there in the first place. @guacs?

[guacs]

This constraint specified in the provided link is for 3.0, but we are using 3.1 which does allow multiple types to be provided for type.

type takes a single value. type as a list is not valid in OpenAPI

The ibm-avoid-multiple-types states that following:

The OpenAPI 3.1 Specification allows multiple types to be used within a schema's type field, but this can create ambiguity in an API definition. Therefore, multiple types should be avoided.

That is, it's part of their linting rules for the spec, but it's not in violation of the spec. However, I feel this is a reasonable rule though and we could default to not using multiple types and instead only provide one type per type field and using anyOf instead.

[nathanielarking]

Heyo @provinzkraut @guacs, thanks for taking a look at this. I had made the initial commits but didn't have time to look into why the CI was failing and if changes needed to be made to any tests. Is that related to the TS changes mentioned? I'll have time later this week to check things out some more.

[guacs]

Is that related to the TS changes mentioned?

Yes, those are the tests that are failing.