chore: token api simplification

[gastonfournier]

About the changes

We found a problem generating the Go SDK client for the tokens API that makes use of oneOf, combined with allOf. The generator doesn't know how to map this type and leaves it as an object. So we tested other generators such as Oval. In this case, Orval manages to create the type but it looks ugly and complex:

export type CreateApiTokenSchema =
| (CreateApiTokenSchemaOneOf & { expiresAt?: string; })
| (CreateApiTokenSchemaOneOfFour & { expiresAt?: string; })
| (CreateApiTokenSchemaOneOfSeven & { expiresAt?: string; })
| (CreateApiTokenSchemaOneOfOnezero & { expiresAt?: string; });

// below are all the one of options. All of is translated to & type combination
export type CreateApiTokenSchemaOneOf = CreateApiTokenSchemaOneOfAllOf & CreateApiTokenSchemaOneOfAllOfTwo;
export type CreateApiTokenSchemaOneOfFour = CreateApiTokenSchemaOneOfFourAllOf & CreateApiTokenSchemaOneOfFourAllOfTwo;
export type CreateApiTokenSchemaOneOfSeven = CreateApiTokenSchemaOneOfSevenAllOf & CreateApiTokenSchemaOneOfSevenAllOfTwo;
export type CreateApiTokenSchemaOneOfOnezero = CreateApiTokenSchemaOneOfOnezeroAllOf & CreateApiTokenSchemaOneOfOnezeroAllOfTwo;

// And then each one individually (note the generated code creates equal types with different names):
export type CreateApiTokenSchemaOneOfAllOf = { type: string; };
export type CreateApiTokenSchemaOneOfAllOfTwo = { tokenName: string; };
export type CreateApiTokenSchemaOneOfFourAllOf = { type: string; };
export type CreateApiTokenSchemaOneOfFourAllOfTwo = { username: string; };
export type CreateApiTokenSchemaOneOfSevenAllOf = { type: string; environment?: string; project?: string; projects?: string[]; };
export type CreateApiTokenSchemaOneOfSevenAllOfTwo = { tokenName: string; };
export type CreateApiTokenSchemaOneOfOnezeroAllOf = { type: string; environment?: string; project?: string; projects?: string[]; };
export type CreateApiTokenSchemaOneOfOnezeroAllOfTwo = { username: string; };

Instead of defining allOf we changed the definition and combined the schemas at runtime. With the change the schema looks much better and this unblocks the generator of Golang SDK:

export type CreateApiTokenSchema =
| (CreateApiTokenSchemaOneOf & { expiresAt?: string; })
| (CreateApiTokenSchemaOneOfTwo & { expiresAt?: string; })
| (CreateApiTokenSchemaOneOfThree & { expiresAt?: string; })
| (CreateApiTokenSchemaOneOfFour & { expiresAt?: string; });

export type CreateApiTokenSchemaOneOf = { type: string; tokenName: string; };
export type CreateApiTokenSchemaOneOfTwo = { type: string; username: string; };
export type CreateApiTokenSchemaOneOfThree = { type: string; environment?: string; project?: string; projects?: string[]; tokenName: string; };
export type CreateApiTokenSchemaOneOfFour = { type: string; environment?: string; project?: string; projects?: string[]; username: string; };

Iterating on this idea, we can include expiresAt as well, and we end up with this:

export type CreateApiTokenSchema =
| CreateApiTokenSchemaOneOf
| CreateApiTokenSchemaOneOfTwo
| CreateApiTokenSchemaOneOfThree
| CreateApiTokenSchemaOneOfFour;

export type CreateApiTokenSchemaOneOf = { expiresAt?: string; type: string; tokenName: string; };
export type CreateApiTokenSchemaOneOfTwo = { expiresAt?: string; type: string; username: string; };
export type CreateApiTokenSchemaOneOfThree = { expiresAt?: string; type: string; environment?: string; project?: string; projects?: string[]; tokenName: string; };
export type CreateApiTokenSchemaOneOfFour = { expiresAt?: string; type: string; environment?: string; project?: string; projects?: string[]; username: string; };

This is closer to what the interface should look like, while the other result is just a consequence of following DRY (avoid duplicated code) and not resolving those references at compile/runtime. Because of that, the references leak to the schema, resulting in additional complexity.

This is what the OpenAPI UI looks like after the change

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

2 Ignored Deployments

Name	Status	Preview	Comments	Updated (UTC)
unleash-docs	⬜️ Ignored (Inspect)	Visit Preview		Sep 4, 2023 1:46pm
unleash-monorepo-frontend	⬜️ Ignored (Inspect)	Visit Preview		Sep 4, 2023 1:46pm

[sighphyre]

❤️