Allow substituting types

[simonbility]

Motivation

Picking up after some time from this issue #375

There are some usecases described here that i think could be addressed by this.

I suspect there are some "bigger picture" decisions (maybe proposals) needing to happen so i wanted to get the ball rolling :)

Modifications

I made a small change allowing to "swap in" any type instead of generating one, by using a vendor-extension (x-swift-open-api-substitute-type)

Result

The following spec

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
components:
  schemas:
    MyCustomString:
      type: string
      x-swift-open-api-substitute-type: MyLibrary.MyCustomString

would generate code like this (abbreviated)

public enum Components {
    public enum Schemas {
        /// - Remark: Generated from `#/components/schemas/MyCustomString`.
        public typealias MyCustomString = MyLibrary.MyCustomString
    }
}

Test Plan

I did write a test but suspect theres, other parts affected that i missed

[simonjbeaumont]

Sorry this went unacknowledged until now, and thank you for taking the time to think about this.

I suspect there are some "bigger picture" decisions (maybe proposals) needing to happen so i wanted to get the ball rolling :)

I'm lightly in favour of this approach since, until we have a holistic solution, it provides an escape-hatch.

We've also previously mentioned that extensions might be a suitable solution to some of these problems: #375 (comment).

It definitely opens up a bunch of questions and caveats. I see this was motivated by the discussion on providing more strongly typed scalar types and agree this is tempting for things like using a UUID type, instead of a string. My biggest concern would be how this would be used with complex schemas and the burden this shifts to adopters for providing a type that satisfies the schema, especially when that schema is itself referenced in other schemas.

Relatedly there was some work in #627 to move targeted types over which is something I'm supportive of but was lacking an API evolution story. Potentially the config to opt-in might be good enough.

Do you see this feature only being valuable if it can provide substitution for richer types or is there value exploring something more targeted?

@czechboy0 WDYT to this too?