From 076b41bb89af6301b0fa9ea2e28c9650a8a8fe2b Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 29 Aug 2022 14:25:17 +0300 Subject: [PATCH] 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 | 2 +- .../admin/discounts/create-condition.ts | 4 +- .../admin/discounts/update-condition.ts | 4 +- .../admin/gift-cards/update-gift-card.ts | 4 +- .../src/models/shipping-method-tax-line.ts | 8 +-- packages/medusa/src/models/shipping-method.ts | 2 +- scripts/build-openapi.js | 51 ++++++++++++------- 7 files changed, 45 insertions(+), 30 deletions(-) diff --git a/.github/workflows/oas-test.yml b/.github/workflows/oas-test.yml index bf71dbe3f0..853ac33bf8 100644 --- a/.github/workflows/oas-test.yml +++ b/.github/workflows/oas-test.yml @@ -31,4 +31,4 @@ jobs: - name: Build OAS run: | - yarn openapi:generate + yarn openapi:generate --dry-run diff --git a/packages/medusa/src/api/routes/admin/discounts/create-condition.ts b/packages/medusa/src/api/routes/admin/discounts/create-condition.ts index f906e47882..a6189525ff 100644 --- a/packages/medusa/src/api/routes/admin/discounts/create-condition.ts +++ b/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: diff --git a/packages/medusa/src/api/routes/admin/discounts/update-condition.ts b/packages/medusa/src/api/routes/admin/discounts/update-condition.ts index 9b8d218e57..b172fdaaa2 100644 --- a/packages/medusa/src/api/routes/admin/discounts/update-condition.ts +++ b/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: diff --git a/packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts b/packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts index f702dca67f..9ba5815d52 100644 --- a/packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts +++ b/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. diff --git a/packages/medusa/src/models/shipping-method-tax-line.ts b/packages/medusa/src/models/shipping-method-tax-line.ts index d25159c6c6..c0153d0ccd 100644 --- a/packages/medusa/src/models/shipping-method-tax-line.ts +++ b/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 diff --git a/packages/medusa/src/models/shipping-method.ts b/packages/medusa/src/models/shipping-method.ts index 9c7ad36d7a..f395d03a81 100644 --- a/packages/medusa/src/models/shipping-method.ts +++ b/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 diff --git a/scripts/build-openapi.js b/scripts/build-openapi.js index bf1eb9280e..c219624ab2 100755 --- a/scripts/build-openapi.js +++ b/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'); + } })