Skip to content

Commit

Permalink
feat(oas) - accurate model OAS representation - A to D (medusajs#3203)
Browse files Browse the repository at this point in the history 
### 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.
  • Loading branch information
@patrick-medusajs
patrick-medusajs authored Feb 8, 2023
1 parent f5dced6 commit 4d3210b
Show file tree
Hide file tree
Showing 22 changed files with 578 additions and 304 deletions.
5 changes: 5 additions & 0 deletions .changeset/young-beers-beg.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@medusajs/medusa": patch
---

feat(oas) - accurate model OAS representation - A to D
65 changes: 47 additions & 18 deletions packages/medusa/src/models/address.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -126,66 +126,93 @@ export class Address extends SoftDeletableEntity {
* title: "Address"
* description: "An address."
* type: object
* required:
* - address_1
* - address_2
* - city
* - company
* - country_code
* - created_at
* - customer_id
* - deleted_at
* - first_name
* - id
* - last_name
* - metadata
* - phone
* - postal_code
* - province
* - updated_at
* properties:
* id:
* type: string
* description: ID of the address
* example: addr_01G8ZC9VS1XVE149MGH2J7QSSH
* customer_id:
* type: string
* description: ID of the customer this address belongs to
* nullable: true
* type: string
* example: cus_01G2SG30J8C85S4A5CHM2S1NS2
* customer:
* description: Available if the relation `customer` is expanded.
* type: array
* items:
* type: object
* description: A customer object.
* nullable: true
* $ref: "#/components/schemas/Customer"
* company:
* type: string
* description: Company name
* nullable: true
* type: string
* example: Acme
* first_name:
* type: string
* description: First name
* nullable: true
* type: string
* example: Arno
* last_name:
* type: string
* description: Last name
* nullable: true
* type: string
* example: Willms
* address_1:
* type: string
* description: Address line 1
* nullable: true
* type: string
* example: 14433 Kemmer Court
* address_2:
* type: string
* description: Address line 2
* nullable: true
* type: string
* example: Suite 369
* city:
* type: string
* description: City
* nullable: true
* type: string
* example: South Geoffreyview
* country_code:
* type: string
* description: The 2 character ISO code of the country in lower case
* nullable: true
* type: string
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
* description: See a list of codes.
* example: st
* country:
* description: A country object. Available if the relation `country` is expanded.
* type: object
* nullable: true
* $ref: "#/components/schemas/Country"
* province:
* type: string
* description: Province
* nullable: true
* type: string
* example: Kentucky
* postal_code:
* type: string
* description: Postal Code
* nullable: true
* type: string
* example: 72093
* phone:
* type: string
* description: Phone Number
* nullable: true
* type: string
* example: 16128234334802
* created_at:
* type: string
Expand All @@ -196,11 +223,13 @@ export class Address extends SoftDeletableEntity {
* description: "The date with timezone at which the resource was updated."
* format: date-time
* deleted_at:
* description: The date with timezone at which the resource was deleted.
* nullable: true
* type: string
* description: "The date with timezone at which the resource was deleted."
* format: date-time
* metadata:
* type: object
* description: An optional key-value map with additional details
* nullable: true
* type: object
* example: {car: "white"}
*/
127 changes: 78 additions & 49 deletions packages/medusa/src/models/batch-job.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,21 +108,36 @@ export class BatchJob extends SoftDeletableEntity {
* description: "A Batch Job."
* type: object
* required:
* - canceled_at
* - completed_at
* - confirmed_at
* - context
* - created_at
* - created_by
* - deleted_at
* - dry_run
* - failed_at
* - id
* - pre_processed_at
* - processing_at
* - result
* - status
* - type
* - updated_at
* properties:
* id:
* description: The unique identifier for the batch job.
* type: string
* description: "The unique identifier for the batch job."
* example: batch_01G8T782965PYFG0751G0Z38B4
* type:
* description: The type of batch job.
* type: string
* description: "The type of batch job."
* enum:
* - product-import
* - product-export
* status:
* description: The status of the batch job.
* type: string
* description: "The status of the batch job."
* enum:
* - created
* - pre_processed
Expand All @@ -133,15 +148,18 @@ export class BatchJob extends SoftDeletableEntity {
* - failed
* default: created
* created_by:
* description: The unique identifier of the user that created the batch job.
* nullable: true
* type: string
* description: "The unique identifier of the user that created the batch job."
* example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
* created_by_user:
* description: A user object. Available if the relation `created_by_user` is expanded.
* type: object
* nullable: true
* $ref: "#/components/schemas/User"
* context:
* description: The context of the batch job, the type of the batch job determines what the context should contain.
* nullable: true
* type: object
* description: "The context of the batch job, the type of the batch job determines what the context should contain."
* example:
* shape:
* prices:
Expand All @@ -159,43 +177,47 @@ export class BatchJob extends SoftDeletableEntity {
* - variant.prices
* - images
* dry_run:
* description: Specify if the job must apply the modifications or not.
* type: boolean
* description: "Specify if the job must apply the modifications or not."
* default: false
* result:
* type: object
* description: "The result of the batch job."
* properties:
* count:
* type: number
* advancement_count:
* type: number
* progress:
* type: number
* errors:
* type: object
* properties:
* message:
* type: string
* code:
* oneOf:
* - type: string
* - type: number
* err:
* type: array
* stat_descriptors:
* type: object
* properties:
* key:
* type: string
* name:
* type: string
* message:
* type: string
* file_key:
* type: string
* file_size:
* type: number
* description: The result of the batch job.
* nullable: true
* allOf:
* - type: object
* example: {}
* - type: object
* properties:
* count:
* type: number
* advancement_count:
* type: number
* progress:
* type: number
* errors:
* type: object
* properties:
* message:
* type: string
* code:
* oneOf:
* - type: string
* - type: number
* err:
* type: array
* stat_descriptors:
* type: object
* properties:
* key:
* type: string
* name:
* type: string
* message:
* type: string
* file_key:
* type: string
* file_size:
* type: number
* example:
* errors:
* - err: []
Expand All @@ -206,39 +228,46 @@ export class BatchJob extends SoftDeletableEntity {
* name: "Product count to export"
* message: "There will be 8 products exported by this action"
* pre_processed_at:
* description: The date from which the job has been pre-processed.
* nullable: true
* type: string
* description: "The date from which the job has been pre processed."
* format: date-time
* processing_at:
* description: The date the job is processing at.
* nullable: true
* type: string
* description: "The date the job is processing at."
* format: date-time
* confirmed_at:
* description: The date when the confirmation has been done.
* nullable: true
* type: string
* description: "The date when the confirmation has been done."
* format: date-time
* completed_at:
* description: The date of the completion.
* nullable: true
* type: string
* description: "The date of the completion."
* format: date-time
* canceled_at:
* description: The date of the concellation.
* nullable: true
* type: string
* description: "The date of the concellation."
* format: date-time
* failed_at:
* description: The date when the job failed.
* nullable: true
* type: string
* description: "The date when the job failed."
* format: date-time
* created_at:
* description: The date with timezone at which the resource was created.
* type: string
* description: "The date with timezone at which the resource was created."
* format: date-time
* updated_at:
* description: The date with timezone at which the resource was last updated.
* type: string
* description: "The date with timezone at which the resource was last updated."
* format: date-time
* deleted_at:
* description: The date with timezone at which the resource was deleted.
* nullable: true
* type: string
* description: "The date with timezone at which the resource was deleted."
* format: date-time
*/
Loading

0 comments on commit 4d3210b

Please sign in to comment.