feat(oas): identify required fields in responses - store (#3282)

## Scope

Store routes

## What

Add OAS `required` to response schemas.

## Why

Code generator can use the `required` property of a schema to mark fields as optional or not when generating TS types.

## Test

* Run `yarn build`
* Run `yarn openapi:generate`
* Run `yarn redocly preview-docs docs/api/store/openapi.yaml --config=docs-util/redocly/config.yaml`
* Open the documentation preview URL in a browser (http://127.0.0.1:8080)
* Expect responses to have their fields declared as `required`

.changeset/short-plants-work.md

@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+feat(oas): identify required fields in responses - store

packages/medusa/src/api/routes/store/auth/index.ts

@@ -22,6 +22,8 @@ export default (app) => {
 /**
  * @schema StoreAuthRes
  * type: object
+ * required:
+ *   - customer
  * properties:
  *   customer:
  *     $ref: "#/components/schemas/Customer"
@@ -33,10 +35,12 @@ export type StoreAuthRes = {
 /**
  * @schema StoreGetAuthEmailRes
  * type: object
+ * required:
+ *   - exists
  * properties:
  *   exists:
- *     type: boolean
  *     description: Whether email exists or not.
+ *     type: boolean
  */
 export type StoreGetAuthEmailRes = {
   exists: boolean

packages/medusa/src/api/routes/store/carts/index.ts

@@ -2,7 +2,7 @@ import "reflect-metadata"
 import { RequestHandler, Router } from "express"
 
 import { Cart, Order, Swap } from "../../../../"
-import { DeleteResponse, FindParams } from "../../../../types/common"
+import { FindParams } from "../../../../types/common"
 import middlewares, {
   transformBody,
   transformQuery,
@@ -160,6 +160,8 @@ export const defaultStoreCartRelations = [
 /**
  * @schema StoreCartsRes
  * type: object
+ * required:
+ *   - cart
  * properties:
  *   cart:
  *     $ref: "#/components/schemas/Cart"
@@ -171,6 +173,9 @@ export type StoreCartsRes = {
 /**
  * @schema StoreCompleteCartRes
  * type: object
+ * required:
+ *   - type
+ *   - data
  * properties:
  *   type:
  *     type: string
@@ -207,8 +212,6 @@ export type StoreCompleteCartRes =
       data: Swap
     }
 
-export type StoreCartsDeleteRes = DeleteResponse
-
 export * from "./add-shipping-method"
 export * from "./create-cart"
 export * from "./create-line-item"

packages/medusa/src/api/routes/store/collections/index.ts

@@ -37,6 +37,11 @@ export const allowedFields = [
 /**
  * @schema StoreCollectionsListRes
  * type: object
+ * required:
+ *   - collections
+ *   - count
+ *   - offset
+ *   - limit
  * properties:
  *   collections:
  *      type: array
@@ -59,6 +64,8 @@ export type StoreCollectionsListRes = PaginatedResponse & {
 /**
  * @schema StoreCollectionsRes
  * type: object
+ * required:
+ *   - collection
  * properties:
  *   collection:
  *     $ref: "#/components/schemas/ProductCollection"

packages/medusa/src/api/routes/store/customers/index.ts

@@ -114,6 +114,8 @@ export const allowedStoreCustomersFields = [
 /**
  * @schema StoreCustomersRes
  * type: object
+ * required:
+ *   - customer
  * properties:
  *   customer:
  *     $ref: "#/components/schemas/Customer"
@@ -125,20 +127,25 @@ export type StoreCustomersRes = {
 /**
  * @schema StoreCustomersListOrdersRes
  * type: object
+ * required:
+ *   - orders
+ *   - count
+ *   - offset
+ *   - limit
  * properties:
  *   orders:
  *     type: array
  *     items:
  *       $ref: "#/components/schemas/Order"
  *   count:
- *     type: integer
  *     description: The total number of items available
+ *     type: integer
  *   offset:
- *     type: integer
  *     description: The number of items skipped before these items
- *   limit:
  *     type: integer
+ *   limit:
  *     description: The number of items per page
+ *     type: integer
  */
 export type StoreCustomersListOrdersRes = PaginatedResponse & {
   orders: Order[]
@@ -147,18 +154,23 @@ export type StoreCustomersListOrdersRes = PaginatedResponse & {
 /**
  * @schema StoreCustomersListPaymentMethodsRes
  * type: object
+ * required:
+ *   - payment_methods
  * properties:
  *   payment_methods:
  *     type: array
  *     items:
  *       type: object
+ *       required:
+ *         - provider_id
+ *         - data
  *       properties:
  *         provider_id:
- *           type: string
  *           description: The id of the Payment Provider where the payment method is saved.
+ *           type: string
  *         data:
- *           type: object
  *           description: The data needed for the Payment Provider to use the saved payment method.
+ *           type: object
  */
 export type StoreCustomersListPaymentMethodsRes = {
   payment_methods: {

packages/medusa/src/api/routes/store/gift-cards/index.ts

@@ -28,6 +28,8 @@ export const allowedStoreGiftCardFields = ["id", "code", "value", "balance"]
 /**
  * @schema StoreGiftCardsRes
  * type: object
+ * required:
+ *   - gift_card
  * properties:
  *   gift_card:
  *     $ref: "#/components/schemas/GiftCard"

packages/medusa/src/api/routes/store/order-edits/index.ts

@@ -44,6 +44,8 @@ export default (app) => {
 /**
  * @schema StoreOrderEditsRes
  * type: object
+ * required:
+ *   - order_edit
  * properties:
  *   order_edit:
  *     $ref: "#/components/schemas/OrderEdit"

packages/medusa/src/api/routes/store/orders/index.ts

@@ -129,6 +129,8 @@ export const allowedStoreOrdersFields = [
 /**
  * @schema StoreOrdersRes
  * type: object
+ * required:
+ *   - order
  * properties:
  *   order:
  *     $ref: "#/components/schemas/Order"

packages/medusa/src/api/routes/store/payment-collections/index.ts

@@ -74,6 +74,8 @@ export const defaultPaymentCollectionRelations = ["region", "payment_sessions"]
 /**
  * @schema StorePaymentCollectionsRes
  * type: object
+ * required:
+ *   - payment_collection
  * properties:
  *   payment_collection:
  *     $ref: "#/components/schemas/PaymentCollection"
@@ -85,6 +87,8 @@ export type StorePaymentCollectionsRes = {
 /**
  * @schema StorePaymentCollectionsSessionRes
  * type: object
+ * required:
+ *   - payment_session
  * properties:
  *   payment_session:
  *     $ref: "#/components/schemas/PaymentSession"

packages/medusa/src/api/routes/store/product-categories/index.ts

@@ -72,6 +72,8 @@ export const allowedStoreProductCategoryFields = [
 /**
  * @schema StoreGetProductCategoriesCategoryRes
  * type: object
+ * required:
+ *   - product_category
  * properties:
  *   product_category:
  *     $ref: "#/components/schemas/ProductCategory"
@@ -83,6 +85,11 @@ export type StoreGetProductCategoriesCategoryRes = {
 /**
  * @schema StoreProductCategoriesListRes
  * type: object
+ * required:
+ *   - product_categories
+ *   - count
+ *   - offset
+ *   - limit
  * properties:
  *   product_categories:
  *      type: array

packages/medusa/src/api/routes/store/product-tags/index.ts

@@ -34,6 +34,29 @@ export const allowedStoreProductTagFields = [...defaultStoreProductTagFields]
 
 export const defaultStoreProductTagRelations = []
 
+/**
+ * @schema StoreProductTagsListRes
+ * type: object
+ * required:
+ *   - product_tags
+ *   - count
+ *   - offset
+ *   - limit
+ * properties:
+ *   product_tags:
+ *      type: array
+ *      items:
+ *        $ref: "#/components/schemas/ProductTag"
+ *   count:
+ *      type: integer
+ *      description: The total number of items available
+ *   offset:
+ *      type: integer
+ *      description: The number of items skipped before these items
+ *   limit:
+ *      type: integer
+ *      description: The number of items per page
+ */
 export type StoreProductTagsListRes = PaginatedResponse & {
   product_tags: ProductTag[]
 }

packages/medusa/src/api/routes/store/product-tags/list-product-tags.ts

@@ -15,6 +15,9 @@ import { IsType } from "../../../../utils/validators/is-type"
  * summary: "List Product Tags"
  * description: "Retrieve a list of Product Tags."
  * x-authenticated: true
+ * x-codegen:
+ *   method: list
+ *   queryParams: StoreGetProductTagsParams
  * parameters:
  *   - (query) limit=20 {integer} The number of types to return.
  *   - (query) offset=0 {integer} The number of items to skip before the results.
@@ -105,19 +108,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/StoreProductTagsListRes"
- *          properties:
- *            product_tags:
- *              $ref: "#/components/schemas/ProductTag"
- *            count:
- *              type: integer
- *              description: The total number of items available
- *            offset:
- *              type: integer
- *              description: The number of items skipped before these items
- *            limit:
- *              type: integer
- *              description: The number of items per page
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

packages/medusa/src/api/routes/store/product-types/index.ts

@@ -42,6 +42,11 @@ export const defaultStoreProductTypeRelations = []
 /**
  * @schema StoreProductTypesListRes
  * type: object
+ * required:
+ *   - product_types
+ *   - count
+ *   - offset
+ *   - limit
  * properties:
  *   product_types:
  *     type: array

packages/medusa/src/api/routes/store/products/index.ts

@@ -113,6 +113,8 @@ export * from "./search"
 /**
  * @schema StoreProductsRes
  * type: object
+ * required:
+ *   - product
  * properties:
  *   product:
  *     $ref: "#/components/schemas/PricedProduct"
@@ -123,20 +125,28 @@ export type StoreProductsRes = {
 
 /**
  * @schema StorePostSearchRes
- * type: object
+ * allOf:
- * properties:
+ *   - type: object
- *   hits:
+ *     required:
- *     type: array
+ *       - hits
- *     description: Array of results. The format of the items depends on the search engine installed on the server.
+ *     properties:
+ *       hits:
+ *         description: Array of results. The format of the items depends on the search engine installed on the server.
+ *         type: array
+ *   - type: object
  */
 export type StorePostSearchRes = {
   hits: unknown[]
-  [k: string]: unknown
+} & Record<string, unknown>
-}
 
 /**
  * @schema StoreProductsListRes
  * type: object
+ * required:
+ *   - products
+ *   - count
+ *   - offset
+ *   - limit
  * properties:
  *   products:
  *     type: array

packages/medusa/src/api/routes/store/regions/index.ts

@@ -16,6 +16,8 @@ export default (app) => {
 /**
  * @schema StoreRegionsListRes
  * type: object
+ * required:
+ *   - regions
  * properties:
  *   regions:
  *     type: array
@@ -29,6 +31,8 @@ export type StoreRegionsListRes = {
 /**
  * @schema StoreRegionsRes
  * type: object
+ * required:
+ *   - region
  * properties:
  *   region:
  *     $ref: "#/components/schemas/Region"

packages/medusa/src/api/routes/store/return-reasons/index.ts

@@ -39,6 +39,8 @@ export const defaultStoreReturnReasonRelations: (keyof ReturnReason)[] = [
 /**
  * @schema StoreReturnReasonsListRes
  * type: object
+ * required:
+ *   - return_reasons
  * properties:
  *   return_reasons:
  *     type: array
@@ -52,6 +54,8 @@ export type StoreReturnReasonsListRes = {
 /**
  * @schema StoreReturnReasonsRes
  * type: object
+ * required:
+ *   - return_reason
  * properties:
  *   return_reason:
  *     $ref: "#/components/schemas/ReturnReason"

packages/medusa/src/api/routes/store/returns/index.ts

@@ -15,6 +15,8 @@ export default (app) => {
 /**
  * @schema StoreReturnsRes
  * type: object
+ * required:
+ *   - return
  * properties:
  *   return:
  *     $ref: "#/components/schemas/Return"

packages/medusa/src/api/routes/store/shipping-options/index.ts

@@ -19,6 +19,8 @@ export default (app) => {
 /**
  * @schema StoreShippingOptionsListRes
  * type: object
+ * required:
+ *   - shipping_options
  * properties:
  *   shipping_options:
  *     type: array

packages/medusa/src/api/routes/store/swaps/index.ts

@@ -49,6 +49,8 @@ export const defaultStoreSwapFields: FindConfig<Swap>["select"] = [
 /**
  * @schema StoreSwapsRes
  * type: object
+ * required:
+ *   - swap
  * properties:
  *   swap:
  *     $ref: "#/components/schemas/Swap"

packages/medusa/src/api/routes/store/variants/index.ts

@@ -32,6 +32,8 @@ export const defaultStoreVariantRelations = ["prices", "options", "product"]
 /**
  * @schema StoreVariantsRes
  * type: object
+ * required:
+ *   - variant
  * properties:
  *   variant:
  *     $ref: "#/components/schemas/PricedVariant"
@@ -43,6 +45,8 @@ export type StoreVariantsRes = {
 /**
  * @schema StoreVariantsListRes
  * type: object
+ * required:
+ *   - variants
  * properties:
  *   variants:
  *     type: array