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
2023-03-09 09:31:40 -05:00
parent 784723a039
commit 4042beb102
14 changed files with 130 additions and 83 deletions
--- a/.changeset/olive-seas-repair.md
+++ b/.changeset/olive-seas-repair.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+feat(oas): add @schema OAS for address request payloads
--- a/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts
+++ b/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.
--- a/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts
+++ b/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."
--- a/packages/medusa/src/api/routes/admin/orders/tests/create-claim.js
+++ b/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

--- a/packages/medusa/src/api/routes/admin/orders/create-claim.ts
+++ b/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
--- a/packages/medusa/src/api/routes/admin/orders/create-swap.ts
+++ b/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."
--- a/packages/medusa/src/api/routes/admin/orders/update-claim.ts
+++ b/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."
--- a/packages/medusa/src/api/routes/admin/orders/update-order.ts
+++ b/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
--- a/packages/medusa/src/api/routes/store/carts/update-cart.ts
+++ b/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
--- a/packages/medusa/src/api/routes/store/customers/create-address.ts
+++ b/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()
--- a/packages/medusa/src/api/routes/store/customers/update-address.ts
+++ b/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 {}
--- a/packages/medusa/src/api/routes/store/customers/update-customer.ts
+++ b/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
--- a/packages/medusa/src/models/address.ts
+++ b/packages/medusa/src/models/address.ts
@@ -66,61 +66,6 @@ export class Address extends SoftDeletableEntity {
  }
 }

-/**
- * @schema AddressFields
- * title: "Address Fields"
- * description: "Address fields used when creating/updating an address."
- * type: object
- * properties:
- *  company:
- *    type: string
- *    description: Company name
- *    example: Acme
- *  first_name:
- *    type: string
- *    description: First name
- *    example: Arno
- *  last_name:
- *    type: string
- *    description: Last name
- *    example: Willms
- *  address_1:
- *    type: string
- *    description: Address line 1
- *    example: 14433 Kemmer Court
- *  address_2:
- *    type: string
- *    description: Address line 2
- *    example: Suite 369
- *  city:
- *    type: string
- *    description: City
- *    example: South Geoffreyview
- *  country_code:
- *    type: string
- *    description: The 2 character ISO code of the country in lower case
- *    externalDocs:
- *      url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
- *      description: See a list of codes.
- *    example: st
- *  province:
- *    type: string
- *    description: Province
- *    example: Kentucky
- *  postal_code:
- *    type: string
- *    description: Postal Code
- *    example: 72093
- *  phone:
- *    type: string
- *    description: Phone Number
- *    example: 16128234334802
- *  metadata:
- *    type: object
- *    description: An optional key-value map with additional details
- *    example: {car: "white"}
- */
-
 /**
 * @schema Address
 * title: "Address"
--- a/packages/medusa/src/types/common.ts
+++ b/packages/medusa/src/types/common.ts
@@ -186,6 +186,57 @@ export class NumericalComparisonOperator {
  lte?: number
 }

+/**
+ * @schema AddressPayload
+ * type: object
+ * description: "Address fields used when creating/updating an address."
+ * properties:
+ *   first_name:
+ *     description: First name
+ *     type: string
+ *     example: Arno
+ *   last_name:
+ *     description: Last name
+ *     type: string
+ *     example: Willms
+ *   phone:
+ *     type: string
+ *     description: Phone Number
+ *     example: 16128234334802
+ *   company:
+ *     type: string
+ *   address_1:
+ *     description: Address line 1
+ *     type: string
+ *     example: 14433 Kemmer Court
+ *   address_2:
+ *     description: Address line 2
+ *     type: string
+ *     example: Suite 369
+ *   city:
+ *     description: City
+ *     type: string
+ *     example: South Geoffreyview
+ *   country_code:
+ *     description: The 2 character ISO code of the country in lower case
+ *     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
+ *   province:
+ *     description: Province
+ *     type: string
+ *     example: Kentucky
+ *   postal_code:
+ *     description: Postal Code
+ *     type: string
+ *     example: 72093
+ *   metadata:
+ *     type: object
+ *     example: {car: "white"}
+ *     description: An optional key-value map with additional details
+ */
 export class AddressPayload {
  @IsOptional()
  @IsString()
@@ -232,6 +283,64 @@ export class AddressPayload {
  postal_code?: string
 }

+/**
+ * @schema AddressCreatePayload
+ * type: object
+ * description: "Address fields used when creating an address."
+ * required:
+ *   - first_name
+ *   - last_name
+ *   - address_1
+ *   - city
+ *   - country_code
+ *   - postal_code
+ * properties:
+ *   first_name:
+ *     description: First name
+ *     type: string
+ *     example: Arno
+ *   last_name:
+ *     description: Last name
+ *     type: string
+ *     example: Willms
+ *   phone:
+ *     type: string
+ *     description: Phone Number
+ *     example: 16128234334802
+ *   company:
+ *     type: string
+ *   address_1:
+ *     description: Address line 1
+ *     type: string
+ *     example: 14433 Kemmer Court
+ *   address_2:
+ *     description: Address line 2
+ *     type: string
+ *     example: Suite 369
+ *   city:
+ *     description: City
+ *     type: string
+ *     example: South Geoffreyview
+ *   country_code:
+ *     description: The 2 character ISO code of the country in lower case
+ *     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
+ *   province:
+ *     description: Province
+ *     type: string
+ *     example: Kentucky
+ *   postal_code:
+ *     description: Postal Code
+ *     type: string
+ *     example: 72093
+ *   metadata:
+ *     type: object
+ *     example: {car: "white"}
+ *     description: An optional key-value map with additional details
+ */
 export class AddressCreatePayload {
  @IsString()
  first_name: string