chore(oas): replace response with $ref to res class JSDoc OAS (Admin A-C) #3002
Conversation
|
| export type AdminBatchJobRes = { | ||
| batch_job: BatchJob | ||
| } | ||
|
|
||
| export type AdminBatchJobDeleteRes = DeleteResponse |
There was a problem hiding this comment.
Couldn't find usage in codebase. Delete operation not implemented.
There was a problem hiding this comment.
indeed, it is mostly for consistency if the client lib want to use it
| export type AdminDeleteProductsFromCollectionRes = { | ||
| id: string | ||
| object: string | ||
| removed_products: string[] | ||
| } |
There was a problem hiding this comment.
admin/collections/remove-products.ts response shape had not equivalent class declared.
Our JS client is wrongfully typed with AdminCollectionsDeleteRes. See file.
| * limit: | ||
| * type: integer | ||
| * description: The number of items per page | ||
| * $ref: "#/components/schemas/AdminCustomersListRes" |
There was a problem hiding this comment.
Note that this endpoint references a response shape from admin/customers/ and not admin/customer-groups/ since it returns a list of customers.
| export type AdminCustomersRes = { | ||
| customer: Customer | ||
| } | ||
|
|
||
| export type AdminCustomersDeleteRes = DeleteResponse |
There was a problem hiding this comment.
Couldn't find usage in codebase. Delete operation not implemented.
Scope
Admin routes directories A to C.
What
Move inline OAS response schema declaration under their respective class declarations in order to expose them through
#/components/schemas. Replace inline OAS response schema with a$refreference pointing to the newly declared schema.Why
Having response declared as its own "named" schema will allow OAS code generators to output typed entities/DTO that can be consumed without having to reference the route/operation.
How
Declare a new @Schema JSDoc for each "Res" class used to parse and validate request body. Move the current inline requestBody to the new @Schema.
Test
Expect no visible changes to the documentation.