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?

[simonbility]

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

No worries at all! i appreciate the response.

I also would classify it as a "escape-hatch" solution and it is inherently "unsafe" as you are relying on manually ensuring that it adheres to the schema...

and i would happily take that tradeoff (obviously 😅)

In our project, where we would like to migrate to generating our models, instead of hand-maintaining them.

The main reasons this escape-hatch would be welcomed are:

• strong-scalars (this is a pretty common and established pattern in our codebase)
• types from external libraries (we would deem it "good enough" to defer the en/de-coding to the library)

I can see this approach breaking down if the schema uses custom "format" without defining a custom named schema.

This would IMO something worth-wile to investigate as well.
In our case this isn't a issue since the spec is in our control, but could be problematic when using a spec vendored by a third-party.

 User:
    type: object
    properties:
      name:
        type: string
      avatar_url: # there is (currently) no way to swap out this type
        type: string
        format: uri