chore(oas): replace response with $ref class JSDoc (Admin O-PRI) #3018
Conversation
|
| * object: | ||
| * type: string | ||
| * description: The type of the object that was deleted. | ||
| * default: item_change |
There was a problem hiding this comment.
Replaced format with default for consistency's sake.
| * object: | ||
| * type: string | ||
| * description: The type of the object that was deleted. | ||
| * default: order_edit |
There was a problem hiding this comment.
Replaced format with default for consistency's sake.
| export type AdminOrdersRes = { | ||
| order: Order | ||
| } | ||
|
|
||
| export type AdminDeleteRes = DeleteResponse |
There was a problem hiding this comment.
Too generic, plus could not find any usage in the codebase.
| * type: integer | ||
| * description: The number of items per page | ||
| */ | ||
| export type AdminPriceListsProductsListRes = PaginatedResponse & { |
There was a problem hiding this comment.
Missing declaration for admin/price-lists/list-price-list-products.ts.
JS client has response typed as any. See file.
| * properties: | ||
| * order_edits: | ||
| * type: array | ||
| * $ref: "#/components/schemas/OrderEdit" |
There was a problem hiding this comment.
The original OAS for this one seems to be incorrect. This should be under the items property since order_edits is an array
There was a problem hiding this comment.
Good catch! Fixed in 5d88100
| * type: boolean | ||
| * description: Whether or not the items were deleted. | ||
| * default: true | ||
| */ | ||
| export type AdminPriceListDeleteBatchRes = { | ||
| ids: string[] | ||
| deleted: boolean | ||
| object: string |
There was a problem hiding this comment.
Not directly related to OAS and isn't necessarily something that should be looked into in this PR: seems like there is an inconsistency across different files in how this type of response is defined. In some places, the default value is set within the type definition (for example, object: 'payment_collection') whereas in other places like here the type is generic. Maybe this is something to take into account if we want to automatically generate OAS comments in the future.
There was a problem hiding this comment.
Indeed. I believe that latest approach is to declare object: as a constant. The way to do it in OAS would be to declare object as the following:
object:
- type: string
- description: The type of the object that was deleted.
- enum: [money-amount]
- default: money-amount
Scope
Admin routes directories O to PRI.
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.