chore(oas): replace requestBody with $ref to req class JSDoc OAS (#2867)
### What Move inline OAS requestBody schema declaration under their respective class-validator classes in order to expose them through `#/components/schemas`. Replace inline OAS requestBody schema with a `$ref` reference pointing to the newly declared schema. ### Why Having requestBody declared as its own "named" schema will allow OAS code generators to output typed entities/DTO that can be manipulate without having to reference the route/operation. ### How Declare a new @schema JSDoc for each class-validator used to parse and validate request body. Move the current inline requestBody to the new @schema. ### Test - Ran OAS validator. - Ran docs build script. Expect no visible changes to the documentation. ### Out-of-scope requestBody of type `multipart/form-data` used for file uploads. These will be address as part of CORE-934 - [create-upload.ts](https://github.com/medusajs/medusa/blob/58d23a7b45b6dde8bdeed0bb268139a0017f1649/packages/medusa/src/api/routes/admin/uploads/create-upload.ts#L87-L90) - [create-protected-upload.ts](https://github.com/medusajs/medusa/blob/58d23a7b45b6dde8bdeed0bb268139a0017f1649/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts#L87-L90) Path Parameter and Query Parameter. These will need more research and experimentation, part of CORE-931 --- Resolves CORE-853
This commit is contained in:
Patrick
@@ -36,93 +36,7 @@ import { IsType } from "../../../../utils/validators/is-type"
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* required:
|
||||
* - email
|
||||
* - region_id
|
||||
* - shipping_methods
|
||||
* properties:
|
||||
* status:
|
||||
* description: "The status of the draft order"
|
||||
* type: string
|
||||
* enum: [open, completed]
|
||||
* email:
|
||||
* description: "The email of the customer of the draft order"
|
||||
* type: string
|
||||
* format: email
|
||||
* billing_address:
|
||||
* description: "The Address to be used for billing purposes."
|
||||
* anyOf:
|
||||
* - $ref: "#/components/schemas/AddressFields"
|
||||
* - type: string
|
||||
* shipping_address:
|
||||
* description: "The Address to be used for shipping."
|
||||
* anyOf:
|
||||
* - $ref: "#/components/schemas/AddressFields"
|
||||
* - type: string
|
||||
* items:
|
||||
* description: The Line Items that have been received.
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - quantity
|
||||
* properties:
|
||||
* variant_id:
|
||||
* description: The ID of the Product Variant to generate the Line Item from.
|
||||
* type: string
|
||||
* unit_price:
|
||||
* description: The potential custom price of the item.
|
||||
* type: integer
|
||||
* title:
|
||||
* description: The potential custom title of the item.
|
||||
* type: string
|
||||
* quantity:
|
||||
* description: The quantity of the Line Item.
|
||||
* type: integer
|
||||
* metadata:
|
||||
* description: The optional key-value map with additional details about the Line Item.
|
||||
* type: object
|
||||
* region_id:
|
||||
* description: The ID of the region for the draft order
|
||||
* type: string
|
||||
* discounts:
|
||||
* description: The discounts to add on the draft order
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - code
|
||||
* properties:
|
||||
* code:
|
||||
* description: The code of the discount to apply
|
||||
* type: string
|
||||
* customer_id:
|
||||
* description: The ID of the customer to add on the draft order
|
||||
* type: string
|
||||
* no_notification_order:
|
||||
* description: An optional flag passed to the resulting order to determine use of notifications.
|
||||
* type: boolean
|
||||
* shipping_methods:
|
||||
* description: The shipping methods for the draft order
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - option_id
|
||||
* properties:
|
||||
* option_id:
|
||||
* description: The ID of the shipping option in use
|
||||
* type: string
|
||||
* data:
|
||||
* description: The optional additional data needed for the shipping method
|
||||
* type: object
|
||||
* price:
|
||||
* description: The potential custom price of the shipping
|
||||
* type: integer
|
||||
* metadata:
|
||||
* description: The optional key-value map with additional details about the Draft Order.
|
||||
* type: object
|
||||
* $ref: "#/components/schemas/AdminPostDraftOrdersReq"
|
||||
* x-codeSamples:
|
||||
* - lang: JavaScript
|
||||
* label: JS Client
|
||||
@@ -249,6 +163,96 @@ enum Status {
|
||||
completed = "completed",
|
||||
}
|
||||
|
||||
/**
|
||||
* @schema AdminPostDraftOrdersReq
|
||||
* type: object
|
||||
* required:
|
||||
* - email
|
||||
* - region_id
|
||||
* - shipping_methods
|
||||
* properties:
|
||||
* status:
|
||||
* description: "The status of the draft order"
|
||||
* type: string
|
||||
* enum: [open, completed]
|
||||
* email:
|
||||
* description: "The email of the customer of the draft order"
|
||||
* type: string
|
||||
* format: email
|
||||
* billing_address:
|
||||
* description: "The Address to be used for billing purposes."
|
||||
* anyOf:
|
||||
* - $ref: "#/components/schemas/AddressFields"
|
||||
* - type: string
|
||||
* shipping_address:
|
||||
* description: "The Address to be used for shipping."
|
||||
* anyOf:
|
||||
* - $ref: "#/components/schemas/AddressFields"
|
||||
* - type: string
|
||||
* items:
|
||||
* description: The Line Items that have been received.
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - quantity
|
||||
* properties:
|
||||
* variant_id:
|
||||
* description: The ID of the Product Variant to generate the Line Item from.
|
||||
* type: string
|
||||
* unit_price:
|
||||
* description: The potential custom price of the item.
|
||||
* type: integer
|
||||
* title:
|
||||
* description: The potential custom title of the item.
|
||||
* type: string
|
||||
* quantity:
|
||||
* description: The quantity of the Line Item.
|
||||
* type: integer
|
||||
* metadata:
|
||||
* description: The optional key-value map with additional details about the Line Item.
|
||||
* type: object
|
||||
* region_id:
|
||||
* description: The ID of the region for the draft order
|
||||
* type: string
|
||||
* discounts:
|
||||
* description: The discounts to add on the draft order
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - code
|
||||
* properties:
|
||||
* code:
|
||||
* description: The code of the discount to apply
|
||||
* type: string
|
||||
* customer_id:
|
||||
* description: The ID of the customer to add on the draft order
|
||||
* type: string
|
||||
* no_notification_order:
|
||||
* description: An optional flag passed to the resulting order to determine use of notifications.
|
||||
* type: boolean
|
||||
* shipping_methods:
|
||||
* description: The shipping methods for the draft order
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - option_id
|
||||
* properties:
|
||||
* option_id:
|
||||
* description: The ID of the shipping option in use
|
||||
* type: string
|
||||
* data:
|
||||
* description: The optional additional data needed for the shipping method
|
||||
* type: object
|
||||
* price:
|
||||
* description: The potential custom price of the shipping
|
||||
* type: integer
|
||||
* metadata:
|
||||
* description: The optional key-value map with additional details about the Draft Order.
|
||||
* type: object
|
||||
*/
|
||||
export class AdminPostDraftOrdersReq {
|
||||
@IsEnum(Status)
|
||||
@IsOptional()
|
||||
|
||||
@@ -26,26 +26,7 @@ import { validator } from "../../../../utils/validator"
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* required:
|
||||
* - quantity
|
||||
* properties:
|
||||
* variant_id:
|
||||
* description: The ID of the Product Variant to generate the Line Item from.
|
||||
* type: string
|
||||
* unit_price:
|
||||
* description: The potential custom price of the item.
|
||||
* type: integer
|
||||
* title:
|
||||
* description: The potential custom title of the item.
|
||||
* type: string
|
||||
* default: "Custom item"
|
||||
* quantity:
|
||||
* description: The quantity of the Line Item.
|
||||
* type: integer
|
||||
* metadata:
|
||||
* description: The optional key-value map with additional details about the Line Item.
|
||||
* type: object
|
||||
* $ref: "#/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsReq"
|
||||
* x-codeSamples:
|
||||
* - lang: JavaScript
|
||||
* label: JS Client
|
||||
@@ -162,6 +143,29 @@ export default async (req, res) => {
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* @schema AdminPostDraftOrdersDraftOrderLineItemsReq
|
||||
* type: object
|
||||
* required:
|
||||
* - quantity
|
||||
* properties:
|
||||
* variant_id:
|
||||
* description: The ID of the Product Variant to generate the Line Item from.
|
||||
* type: string
|
||||
* unit_price:
|
||||
* description: The potential custom price of the item.
|
||||
* type: integer
|
||||
* title:
|
||||
* description: The potential custom title of the item.
|
||||
* type: string
|
||||
* default: "Custom item"
|
||||
* quantity:
|
||||
* description: The quantity of the Line Item.
|
||||
* type: integer
|
||||
* metadata:
|
||||
* description: The optional key-value map with additional details about the Line Item.
|
||||
* type: object
|
||||
*/
|
||||
export class AdminPostDraftOrdersDraftOrderLineItemsReq {
|
||||
@IsString()
|
||||
@IsOptional()
|
||||
|
||||
@@ -32,48 +32,7 @@ import { IsType } from "../../../../utils/validators/is-type"
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* region_id:
|
||||
* type: string
|
||||
* description: The ID of the Region to create the Draft Order in.
|
||||
* country_code:
|
||||
* type: string
|
||||
* description: "The 2 character ISO code for the Country."
|
||||
* externalDocs:
|
||||
* url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
|
||||
* description: See a list of codes.
|
||||
* email:
|
||||
* type: string
|
||||
* description: "An email to be used on the Draft Order."
|
||||
* format: email
|
||||
* billing_address:
|
||||
* description: "The Address to be used for billing purposes."
|
||||
* anyOf:
|
||||
* - $ref: "#/components/schemas/AddressFields"
|
||||
* - type: string
|
||||
* shipping_address:
|
||||
* description: "The Address to be used for shipping."
|
||||
* anyOf:
|
||||
* - $ref: "#/components/schemas/AddressFields"
|
||||
* - type: string
|
||||
* discounts:
|
||||
* description: "An array of Discount codes to add to the Draft Order."
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - code
|
||||
* properties:
|
||||
* code:
|
||||
* description: "The code that a Discount is identifed by."
|
||||
* type: string
|
||||
* no_notification_order:
|
||||
* description: "An optional flag passed to the resulting order to determine use of notifications."
|
||||
* type: boolean
|
||||
* customer_id:
|
||||
* description: "The ID of the Customer to associate the Draft Order with."
|
||||
* type: string
|
||||
* $ref: "#/components/schemas/AdminPostDraftOrdersDraftOrderReq"
|
||||
* x-codeSamples:
|
||||
* - lang: JavaScript
|
||||
* label: JS Client
|
||||
@@ -182,6 +141,51 @@ export default async (req, res) => {
|
||||
res.status(200).json({ draft_order: draftOrder })
|
||||
}
|
||||
|
||||
/**
|
||||
* @schema AdminPostDraftOrdersDraftOrderReq
|
||||
* type: object
|
||||
* properties:
|
||||
* region_id:
|
||||
* type: string
|
||||
* description: The ID of the Region to create the Draft Order in.
|
||||
* country_code:
|
||||
* type: string
|
||||
* description: "The 2 character ISO code for the Country."
|
||||
* externalDocs:
|
||||
* url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
|
||||
* description: See a list of codes.
|
||||
* email:
|
||||
* type: string
|
||||
* description: "An email to be used on the Draft Order."
|
||||
* format: email
|
||||
* billing_address:
|
||||
* description: "The Address to be used for billing purposes."
|
||||
* anyOf:
|
||||
* - $ref: "#/components/schemas/AddressFields"
|
||||
* - type: string
|
||||
* shipping_address:
|
||||
* description: "The Address to be used for shipping."
|
||||
* anyOf:
|
||||
* - $ref: "#/components/schemas/AddressFields"
|
||||
* - type: string
|
||||
* discounts:
|
||||
* description: "An array of Discount codes to add to the Draft Order."
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - code
|
||||
* properties:
|
||||
* code:
|
||||
* description: "The code that a Discount is identifed by."
|
||||
* type: string
|
||||
* no_notification_order:
|
||||
* description: "An optional flag passed to the resulting order to determine use of notifications."
|
||||
* type: boolean
|
||||
* customer_id:
|
||||
* description: "The ID of the Customer to associate the Draft Order with."
|
||||
* type: string
|
||||
*/
|
||||
export class AdminPostDraftOrdersDraftOrderReq {
|
||||
@IsString()
|
||||
@IsOptional()
|
||||
|
||||
@@ -25,20 +25,7 @@ import { validator } from "../../../../utils/validator"
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* unit_price:
|
||||
* description: The potential custom price of the item.
|
||||
* type: integer
|
||||
* title:
|
||||
* description: The potential custom title of the item.
|
||||
* type: string
|
||||
* quantity:
|
||||
* description: The quantity of the Line Item.
|
||||
* type: integer
|
||||
* metadata:
|
||||
* description: The optional key-value map with additional details about the Line Item.
|
||||
* type: object
|
||||
* $ref: "#/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsItemReq"
|
||||
* x-codeSamples:
|
||||
* - lang: JavaScript
|
||||
* label: JS Client
|
||||
@@ -157,6 +144,23 @@ export default async (req, res) => {
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* @schema AdminPostDraftOrdersDraftOrderLineItemsItemReq
|
||||
* type: object
|
||||
* properties:
|
||||
* unit_price:
|
||||
* description: The potential custom price of the item.
|
||||
* type: integer
|
||||
* title:
|
||||
* description: The potential custom title of the item.
|
||||
* type: string
|
||||
* quantity:
|
||||
* description: The quantity of the Line Item.
|
||||
* type: integer
|
||||
* metadata:
|
||||
* description: The optional key-value map with additional details about the Line Item.
|
||||
* type: object
|
||||
*/
|
||||
export class AdminPostDraftOrdersDraftOrderLineItemsItemReq {
|
||||
@IsString()
|
||||
@IsOptional()
|
||||
|
||||
Reference in New Issue
Block a user