Spike: Constrain the OpenAPI schema emitted for a model [DO NOT MERGE]

[bajtos]

This pull request offers a PoC implementation demonstrating how to modify the schema generated from a LB4 model depending on configurable options. In particular, the following two use cases are covered:

• PATCH - all properties are optional
• CREATE - id and possibly _rev must not be present

The first commit imports code from #2592 and should be ignored.

The second commit contains PoC and SPIKE notes with a high-level overview.

Related stories:

• the spike story: [Spike] Reference a Model/type and add additional constraints #2082
• Partial update (PATCH) over REST #1722
• OpenAPI decorator does not properly generate schemas of type Partial #1179
• [API Explorer] Fields shown but ignored #1470
• relation expects foreignKey on the Object #1719
• fix(rest): allow @patch update obj to be a Partial #1894

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

[bajtos]

This type construct allows TypeScript to verify that exclude is using only existing model properties.

Consider the following incorrect usage:

{
  schema: getModelSchemaRef(TodoList, {exclude: ['id', 'foobar']}),
}

The compiler prints the following error:

Argument of type '{ exclude: ("id" | "foobar")[]; }' is not assignable to parameter of type 'JsonSchemaOptions<TodoList>'.
  Types of property 'exclude' are incompatible.
    Type '("id" | "foobar")[]' is not assignable to type '("id" | "title" | "color" | "todos" | "image" | "getId" | "getIdObject" | "toJSON" | "toObject")[]'.
      Type '"id" | "foobar"' is not assignable to type '"id" | "title" | "color" | "todos" | "image" | "getId" | "getIdObject" | "toJSON" | "toObject"'.
        Type '"foobar"' is not assignable to type '"id" | "title" | "color" | "todos" | "image" | "getId" | "getIdObject" | "toJSON" | "toObject"'.

[raymondfeng]

Maybe define a type alias:

export type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;

[bajtos]

+1 to define a type alias.

We must carefully choose a name that will be different enough from Exclude. Few options that come to my mind:

• ExcludeProperties<T, K>
• ExcludeKeys<T, K>
• OmitProperties<T, K>
• OmitKeys<T, K>

[jannyHou]

The design that customizes the schema by options LGTM 👍

[bajtos]

Created the following stories:

• Emit schema with all model properties optional Emit schema with all model properties optional #2652
• Emit schema excluding certain model properties Emit schema excluding certain model properties #2653
• Spike: simplify requestBody annotation with schema options Spike: simplify requestBody annotation with schema options #2654

Closing this spike as done.