feat(oas): add @schema OAS for address request payloads (#3423)

## What

Replace AddressFields with actual AddressPayload schema based off the actual type used by the controllers.

## Why

AddressPayload is currently being referenced in client code. Our OAS schema should attempt to match current client usage in order to reduce friction when migrating to a OAS generated types package.

## How

* Represent AddressPayload and AddressCreatePayload in our OAS schemas.
* Replace reference to AddressFields
* Plus, fix typo in /admin/orders/ route

packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts

@@ -181,12 +181,12 @@ enum Status {
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   shipping_address:
  *     description: "The Address to be used for shipping."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   items:
  *     description: The Line Items that have been received.

packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts

@@ -160,12 +160,12 @@ export default async (req, res) => {
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   shipping_address:
  *     description: "The Address to be used for shipping."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   discounts:
  *     description: "An array of Discount codes to add to the Draft Order."

packages/medusa/src/api/routes/admin/orders/__tests__/create-claim.js

@@ -2,7 +2,7 @@ import { IdMap } from "medusa-test-utils"
 import { request } from "../../../../../helpers/test-request"
 import { ClaimServiceMock } from "../../../../../services/__mocks__/claim"
 
-describe("POST /admin/order/:id/claims", () => {
+describe("POST /admin/orders/:id/claims", () => {
   describe("successfully creates a claim", () => {
     let subject
 

packages/medusa/src/api/routes/admin/orders/create-claim.ts

@@ -18,7 +18,7 @@ import { ClaimTypeValue } from "../../../../types/claim"
 import { AddressPayload, FindParams } from "../../../../types/common"
 
 /**
- * @oas [post] /admin/order/{id}/claims
+ * @oas [post] /admin/orders/{id}/claims
  * operationId: "PostOrdersOrderClaims"
  * summary: "Create a Claim"
  * description: "Creates a Claim."
@@ -383,9 +383,8 @@ export default async (req, res) => {
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
  *   shipping_address:
- *      type: object
  *      description: "An optional shipping address to send the claim to. Defaults to the parent order's shipping address"
- *      $ref: "#/components/schemas/Address"
+ *      $ref: "#/components/schemas/AddressPayload"
  *   refund_amount:
  *      description: The amount to refund the Customer when the Claim type is `refund`.
  *      type: integer

packages/medusa/src/api/routes/admin/orders/create-swap.ts

@@ -23,7 +23,7 @@ import { Type } from "class-transformer"
 import { FindParams } from "../../../../types/common"
 
 /**
- * @oas [post] /admin/order/{id}/swaps
+ * @oas [post] /admin/orders/{id}/swaps
  * operationId: "PostOrdersOrderSwaps"
  * summary: "Create a Swap"
  * description: "Creates a Swap. Swaps are used to handle Return of previously purchased goods and Fulfillment of replacements simultaneously."

packages/medusa/src/api/routes/admin/orders/update-claim.ts

@@ -16,7 +16,7 @@ import { validator } from "../../../../utils/validator"
 import { FindParams } from "../../../../types/common"
 
 /**
- * @oas [post] /admin/order/{id}/claims/{claim_id}
+ * @oas [post] /admin/orders/{id}/claims/{claim_id}
  * operationId: "PostOrdersOrderClaimsClaim"
  * summary: "Update a Claim"
  * description: "Updates a Claim."

packages/medusa/src/api/routes/admin/orders/update-order.ts

@@ -108,12 +108,10 @@ export default async (req, res) => {
  *     type: string
  *   billing_address:
  *     description: Billing address
- *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *     $ref: "#/components/schemas/AddressPayload"
  *   shipping_address:
  *     description: Shipping address
- *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *     $ref: "#/components/schemas/AddressPayload"
  *   items:
  *     description: The Line Items for the order
  *     type: array

packages/medusa/src/api/routes/store/carts/update-cart.ts

@@ -136,14 +136,14 @@ class Discount {
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
  *     anyOf:
- *       - $ref: "#/components/schemas/Address"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *         description: A full billing address object.
  *       - type: string
  *         description: The billing address ID
  *   shipping_address:
  *     description: "The Address to be used for shipping."
  *     anyOf:
- *       - $ref: "#/components/schemas/Address"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *         description: A full shipping address object.
  *       - type: string
  *         description: The shipping address ID

packages/medusa/src/api/routes/store/customers/create-address.ts

@@ -117,16 +117,7 @@ export default async (req, res) => {
  * properties:
  *   address:
  *     description: "The Address to add to the Customer."
- *     allOf:
- *       - $ref: "#/components/schemas/AddressFields"
- *       - type: object
- *         required:
- *           - first_name
- *           - last_name
- *           - address_1
- *           - city
- *           - country_code
- *           - postal_code
+ *     $ref: "#/components/schemas/AddressCreatePayload"
  */
 export class StorePostCustomersCustomerAddressesReq {
   @ValidateNested()

packages/medusa/src/api/routes/store/customers/update-address.ts

@@ -98,7 +98,7 @@ export default async (req, res) => {
 /**
  * @schema StorePostCustomersCustomerAddressesAddressReq
  * anyOf:
- *   - $ref: "#/components/schemas/AddressFields"
+ *   - $ref: "#/components/schemas/AddressPayload"
  */
 // eslint-disable-next-line max-len
 export class StorePostCustomersCustomerAddressesAddressReq extends AddressPayload {}

packages/medusa/src/api/routes/store/customers/update-customer.ts

@@ -100,7 +100,7 @@ export default async (req, res) => {
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *         description: The full billing address object
  *       - type: string
  *         description: The ID of an existing billing address