Multiple Version Support Plan

[pmcelhaney]

Given a spec like the following:

spec:
  - source: https://petstore.swagger.io/v2/swagger.json
    group: petstore
    version: v2 
  - source: https://petstore3.swagger.io/api/v3/openapi.json
    group: petstore
    version: v3
destination: out

Counterfact should load both versions of the Petstore API. The server should host the APIs at the following URLs:

• https://localhost:3100/petstore/v2
• https://localhost:3100/petstore/v3

For the most part, the generated code supporting these two APIs will be shared. TypeCoders except for OperationTypeCoder will put their output in subdirectories according to the version property passed into them. (SchemaTypeCoder and ResponseTypeCoder already do that; the others will need to be updated.)

OperationTypeCoder will output code that maps to each of the versions. It will look something like this:

// ./types/paths/some/path.ts

type HTTP_GET_$_Versions = {
  "v2": ($: /* type constructed from types in v2 files */) => MaybePromise<COUNTERFACT_RESPONSE>;
  "v3": ($: /* type constructed from types in v3 files */) => MaybePromise<COUNTERFACT_RESPONSE>;
};

export type HTTP_GET = ($: Versioned<HTTP_GET_$_Versions>) => COUNTERFACT_RESPONSE;

The Versioned type will be created in a new file under ./out/types/versions.ts

export type Versions = "v2" | "v3";

export type VersionsGTE = {
  "v3: "v2" | "v3";
  "v3": "v3";
};

type VersionMap = Partial<Record<Versions, object>>;


export type Versioned<
  T extends VersionMap,
  V extends keyof T & Versions = keyof T & Versions,
> = T[V] & {
  version: V;
  minVersion<M extends keyof T & Versions>(
    min: M,
  ): this is Versioned<T, Extract<V, VersionsGTE[M]>>;

Some of the plumbing needed for these changes was added in recent commits.

Create an issue that documents the overall approach for implementing multiple version support, including what changes will need to be made in the server, code generator, core / app code, the REPL, the scenarios, the documentation, etc. Do not write any code yet.