fix(docs): API reference bugs (#2119)

* fixed shipping method tax line schema name

* added dry run option to build openapi script

* fixed summary of endpoints

* fixed title of endpoint

.github/workflows/oas-test.yml

@@ -31,4 +31,4 @@ jobs:
 
       - name: Build OAS
         run: |
-          yarn openapi:generate
+          yarn openapi:generate --dry-run

packages/medusa/src/api/routes/admin/discounts/create-condition.ts

@@ -12,13 +12,13 @@ import { validator } from "../../../../utils/validator"
 /**
  * @oas [post] /discounts/{discount_id}/conditions
  * operationId: "PostDiscountsDiscountConditions"
- * summary: "Creates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
+ * summary: "Create a DiscountCondition"
+ * description: "Creates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
  * x-authenticated: true
  * parameters:
  *   - (path) discount_id=* {string} The ID of the Product.
  *   - (query) expand {string} (Comma separated) Which fields should be expanded in each product of the result.
  *   - (query) fields {string} (Comma separated) Which fields should be included in each product of the result.
- * description: "Creates a DiscountCondition"
  * requestBody:
  *   content:
  *     application/json:

packages/medusa/src/api/routes/admin/discounts/update-condition.ts

@@ -12,14 +12,14 @@ import { validator } from "../../../../utils/validator"
 /**
  * @oas [post] /discounts/{discount_id}/conditions/{condition_id}
  * operationId: "PostDiscountsDiscountConditionsCondition"
- * summary: "Updates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
+ * summary: "Update a DiscountCondition"
+ * description: "Updates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
  * x-authenticated: true
  * parameters:
  *   - (path) discount_id=* {string} The ID of the Product.
  *   - (path) condition_id=* {string} The ID of the DiscountCondition.
  *   - (query) expand {string} (Comma separated) Which fields should be expanded in each item of the result.
  *   - (query) fields {string} (Comma separated) Which fields should be included in each item of the result.
- * description: "Updates a DiscountCondition"
  * requestBody:
  *   content:
  *     application/json:

packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts

@@ -9,8 +9,8 @@ import { EntityManager } from "typeorm"
 /**
  * @oas [post] /gift-cards/{id}
  * operationId: "PostGiftCardsGiftCard"
- * summary: "Create a Gift Card"
- * description: "Creates a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region."
+ * summary: "Update a Gift Card"
+ * description: "Update a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Gift Card.

packages/medusa/src/models/shipping-method-tax-line.ts

@@ -30,10 +30,10 @@ export class ShippingMethodTaxLine extends TaxLine {
 }
 
 /**
- * @schema sales_channel_tax_line
- * title: "Sales Channel"
- * description: "A Sales Channel"
- * x-resourceId: sales_channel_tax_line
+ * @schema shipping_method_tax_line
+ * title: "Shipping Method Tax Line"
+ * description: "Shipping Method Tax Line"
+ * x-resourceId: shipping_method_tax_line
  * required:
  *   - shipping_method_id
  *   - rate

packages/medusa/src/models/shipping-method.ts

@@ -154,7 +154,7 @@ export class ShippingMethod {
  *     type: array
  *     description: Available if the relation `tax_lines` is expanded.
  *     items:
- *       $ref: "#/components/schemas/tax_line"
+ *       $ref: "#/components/schemas/shipping_method_tax_line"
  *   price:
  *     description: "The amount to charge for the Shipping Method. The currency of the price is defined by the Region that the Order that the Shipping Method belongs to is a part of."
  *     type: integer

scripts/build-openapi.js

@@ -3,7 +3,10 @@
 const fs = require("fs")
 const OAS = require("oas-normalize")
 const swaggerInline = require("swagger-inline")
-const { exec } = require("child_process")
+const { exec } = require("child_process");
+const { exit } = require("process");
+
+const isDryRun = process.argv.indexOf('--dry-run') !== -1;
 
 // Storefront API
 swaggerInline(
@@ -16,7 +19,9 @@ swaggerInline(
   oas
     .validate(true)
     .then(() => {
-      fs.writeFileSync("./docs/api/store-spec3.json", gen)
+      if (!isDryRun) {
+        fs.writeFileSync("./docs/api/store-spec3.json", gen)
+      }
     })
     .catch((err) => {
       console.log("Error in store")
@@ -32,13 +37,17 @@ swaggerInline(
     format: "yaml",
   }
 ).then((gen) => {
-  fs.writeFileSync("./docs/api/store-spec3.yaml", gen)
-  exec("rm -rf docs/api/store/ && yarn run -- redocly split docs/api/store-spec3.yaml --outDir=docs/api/store/", (error, stdout, stderr) => {
-    if (error) {
-      throw new Error(`error: ${error.message}`)
-    }
-    console.log(`${stderr || stdout}`);
-  });
+  if (!isDryRun) {
+    fs.writeFileSync("./docs/api/store-spec3.yaml", gen)
+    exec("rm -rf docs/api/store/ && yarn run -- redocly split docs/api/store-spec3.yaml --outDir=docs/api/store/", (error, stdout, stderr) => {
+      if (error) {
+        throw new Error(`error: ${error.message}`)
+      }
+      console.log(`${stderr || stdout}`);
+    });
+  } else {
+    console.log('No errors occurred while generating Store API Reference');
+  }
 })
 
 // Admin API
@@ -52,7 +61,9 @@ swaggerInline(
   oas
     .validate(true)
     .then(() => {
-      fs.writeFileSync("./docs/api/admin-spec3.json", gen)
+      if (!isDryRun) {
+        fs.writeFileSync("./docs/api/admin-spec3.json", gen)
+      }
     })
     .catch((err) => {
       console.log("Error in admin")
@@ -68,12 +79,16 @@ swaggerInline(
     format: "yaml",
   }
 ).then((gen) => {
-  fs.writeFileSync("./docs/api/admin-spec3.yaml", gen)
-  exec("rm -rf docs/api/admin/ && yarn run -- redocly split docs/api/admin-spec3.yaml --outDir=docs/api/admin/", (error, stdout, stderr) => {
-    if (error) {
-        throw new Error(`error: ${error.message}`)
-    }
-    console.log(`${stderr || stdout}`);
-    return;
-  });
+  if (!isDryRun) {
+    fs.writeFileSync("./docs/api/admin-spec3.yaml", gen)
+    exec("rm -rf docs/api/admin/ && yarn run -- redocly split docs/api/admin-spec3.yaml --outDir=docs/api/admin/", (error, stdout, stderr) => {
+      if (error) {
+          throw new Error(`error: ${error.message}`)
+      }
+      console.log(`${stderr || stdout}`);
+      return;
+    });
+  } else {
+    console.log('No errors occurred while generating Admin API Reference');
+  }
 })