feat(oas) - accurate model OAS representation - A to D #3203
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
🦋 Changeset detectedLatest commit: a8fa726 The changes in this PR will be included in the next version bump. This PR includes changesets to release 2 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
patrick-medusajs
commented
Feb 8, 2023
There was a problem hiding this comment.
self-review: I'd recommend using the Model TS refactor PR to facilitate the review process. I've also create a demo PR to showcase the generate types from the OAS.
|
Has a dependency on #3198 getting merged in order for Redocly to not crash when rendering the circular references in this PR. |
shahednasser
requested changes
Feb 8, 2023
shahednasser
approved these changes
Feb 8, 2023
adrien2p
pushed a commit
that referenced
this pull request
Feb 13, 2023
### Scope
Models A to D
### What
Refactor OAS for models to accurately represent their shape in API responses.
### Why
About 33% of model fields are not accurately represented in the OAS. Most of the issues are:
- fields that can not be omitted in the response are not declared as `required`
- fields that could return `null` as their value are not declared as `nullable: true`
When using a code generator, these OAS issues would lead to inaccurate response shapes in the generated client.
### How
#### nullable
Fields meeting at least one of the following condition will be represented as `nullable: true` in OAS:
* The field is decorated with `@Column({ nullable: true })`
* The field is decorated with `@OneToOne`, `@ManyToOne`
* The field is decorated with `@DeleteDateColumn`
#### optional
Fields meeting at least one of the following conditions will never be listed as `required` in OAS and will be considered optional and could be omitted in the response:
* The field is decorated with `@OneToOne`, `@ManyToOne`, `@OneToMany`, `@ManyToMany`
* The field is decorated with `@FeatureFlagColumn`
* The field is decorated with `@Column({select: false})`
* The field is representing dynamic values not persisted in the database
Fields not meeting any of the conditions above will be declared as `required` and are expected to be present in the response.
### Test
* Ran OAS validator.
* Ran docs build script.
Expect OAS changes to be reflected in the API documentation.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Scope
Models A to D
What
Refactor OAS for models to accurately represent their shape in API responses.
Why
About 33% of model fields are not accurately represented in the OAS. Most of the issues are:
requirednullas their value are not declared asnullable: trueWhen using a code generator, these OAS issues would lead to inaccurate response shapes in the generated client.
How
nullable
Fields meeting at least one of the following condition will be represented as
nullable: truein OAS:@Column({ nullable: true })@OneToOne,@ManyToOne@DeleteDateColumnoptional
Fields meeting at least one of the following conditions will never be listed as
requiredin OAS and will be considered optional and could be omitted in the response:@OneToOne,@ManyToOne,@OneToMany,@ManyToMany@FeatureFlagColumn@Column({select: false})Fields not meeting any of the conditions above will be declared as
requiredand are expected to be present in the response.Test
Expect OAS changes to be reflected in the API documentation.