feat(medusa-oas-cli): updated redocly-cli to v1.7 (#6211)

## What

Updates `@redocly/cli` to v1.7. This resolves the bug of TypeScript and tsx code samples in the OAS being generated as undefined files (see files under `www/apps/api-reference/specs/admin/code_samples/tsx` and `www/apps/api-reference/specs/store/code_samples/tsx`

I avoided re-generating OAS so that this PR doesn't have a huge diff. When the next release is out, an automated PR will be opened to update the OAS files, replacing the undefined files with `.tsx` files.

### Other Changes

- Small fixes to `medusa-oas-cli` README for clarity

packages/oas/medusa-oas-cli/README.md

@@ -167,7 +167,7 @@ Specify in which directory should the files be outputted. Accepts relative and a
 If the directory doesn't exist, it will be created. Defaults to `./`.
 
 ```bash
-yarn medusa-oas docs --out-dir ./docs`
+yarn medusa-oas docs --src-file ./store.oas.json --out-dir ./docs`
 ```
 
 #### `--config <path>`
@@ -175,7 +175,7 @@ yarn medusa-oas docs --out-dir ./docs`
 Specify the path to a Redocly config file.
 
 ```bash
-yarn medusa-oas --config ./redocly-config.yaml
+yarn medusa-oas --src-file ./store.oas.json --config ./redocly-config.yaml
 ```
 
 #### `--dry-run`
@@ -183,7 +183,7 @@ yarn medusa-oas --config ./redocly-config.yaml
 Will sanitize the OAS but will not output file. Useful for troubleshooting circular reference issues.
 
 ```bash
-yarn medusa-oas docs --dry-run
+yarn medusa-oas docs --src-file ./store.oas.json --dry-run
 ```
 
 #### `--clean`
@@ -191,7 +191,7 @@ yarn medusa-oas docs --dry-run
 Delete destination directory content before generating client.
 
 ```bash
-yarn medusa-oas docs --clean
+yarn medusa-oas docs --src-file ./store.oas.json --clean
 ```
 
 #### `--split`
@@ -199,7 +199,7 @@ yarn medusa-oas docs --clean
 Creates a multi-file structure output. Uses `redocly split` internally.
 
 ```bash
-yarn medusa-oas docs --split
+yarn medusa-oas docs --src-file ./store.oas.json --split
 ```
 
 #### `--preview`
@@ -207,7 +207,7 @@ yarn medusa-oas docs --split
 Generate a preview of the API documentation in a browser. Does not output files. Uses `redocly preview-docs` internally.
 
 ```bash
-yarn medusa-oas docs --preview
+yarn medusa-oas docs --src-file ../../../www/apps/api-reference/specs/store.oas.json --preview
 ```
 
 #### `--html`
@@ -215,5 +215,5 @@ yarn medusa-oas docs --preview
 Generate a zero-dependency static HTML file. Uses `redocly build-docs` internally.
 
 ```bash
-yarn medusa-oas docs --html
+yarn medusa-oas docs --src-file ./store.oas.json --html
 ```

packages/oas/medusa-oas-cli/package.json

@@ -21,6 +21,7 @@
   "author": "Medusa",
   "license": "MIT",
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "jest": "^29.1.0",
     "js-yaml": "^4.1.0",
     "ts-jest": "^29.1.0",
@@ -40,12 +41,13 @@
     "@medusajs/utils": "^1.10.5",
     "@readme/json-schema-ref-parser": "^1.2.0",
     "@readme/openapi-parser": "^2.4.0",
-    "@redocly/cli": "1.0.0-beta.123",
+    "@redocly/cli": "^1.7.0",
     "@types/lodash": "^4.14.191",
     "commander": "^10.0.0",
     "execa": "1.0.0",
     "lodash": "^4.17.21",
     "openapi3-ts": "^3.1.2",
-    "swagger-inline": "^6.1.0"
+    "swagger-inline": "^6.1.0",
+    "yargs": "^17.7.2"
   }
 }

packages/oas/medusa-oas-cli/src/command-docs.ts

@@ -1,4 +1,5 @@
-import { previewDocs } from "@redocly/cli/lib/commands/preview-docs"
+import { PreviewDocsOptions, previewDocs } from "@redocly/cli/lib/commands/preview-docs"
+import { commandWrapper } from "@redocly/cli/lib/wrapper"
 import { Command, Option, OptionValues } from "commander"
 import execa from "execa"
 import fs, { mkdir } from "fs/promises"
@@ -11,7 +12,8 @@ import {
 } from "./utils/circular-patch-utils"
 import { getTmpDirectory, isFile } from "./utils/fs-utils"
 import { readJson } from "./utils/json-utils"
-import { jsonFileToYamlFile, readYaml, writeYaml } from "./utils/yaml-utils"
+import { jsonFileToYamlFile, readYaml, writeYaml, writeYamlFromJson } from "./utils/yaml-utils"
+import yargs from "yargs"
 
 /**
  * Constants
@@ -131,7 +133,7 @@ export async function execute(cliParams: OptionValues): Promise<void> {
     await mkdir(outDir, { recursive: true })
   }
 
-  const srcFileSanitized = path.resolve(tmpDir, "tmp.oas.json")
+  const srcFileSanitized = path.resolve(tmpDir, "tmp.oas.yaml")
   await sanitizeOAS(srcFile, srcFileSanitized, configTmpFile)
   await circularReferenceCheck(srcFileSanitized)
 
@@ -146,7 +148,7 @@ export async function execute(cliParams: OptionValues): Promise<void> {
   if (shouldSplit) {
     await generateReference(srcFileSanitized, outDir)
   } else {
-    await jsonFileToYamlFile(srcFileSanitized, path.join(outDir, finalOASFile))
+    await writeYaml(path.join(outDir, finalOASFile), await fs.readFile(srcFileSanitized, "utf8"))
   }
   if (shouldBuildHTML) {
     const outHTMLFile = path.resolve(outDir, "index.html")
@@ -186,7 +188,7 @@ const mergeConfig = async (
     isArray(objValue) ? objValue.concat(srcValue) : undefined
   ) as RedoclyConfig
 
-  await writeYaml(configFileOut, config)
+  await writeYamlFromJson(configFileOut, config)
 }
 
 const createTmpConfig = async (
@@ -199,7 +201,7 @@ const createTmpConfig = async (
   )
   config.plugins.push(medusaPluginAbsolutePath)
 
-  await writeYaml(configFileOut, config)
+  await writeYamlFromJson(configFileOut, config)
 }
 
 const sanitizeOAS = async (
@@ -254,12 +256,12 @@ const generateReference = async (
 }
 
 const preview = async (oasFile: string, configFile: string): Promise<void> => {
-  await previewDocs({
+  await commandWrapper(previewDocs)({
     port: 8080,
     host: "127.0.0.1",
     api: oasFile,
     config: configFile,
-  })
+  } as yargs.Arguments<PreviewDocsOptions>)
 }
 
 const buildHTML = async (

packages/oas/medusa-oas-cli/src/utils/yaml-utils.ts

@@ -6,7 +6,11 @@ export const readYaml = async (filePath): Promise<unknown> => {
   return yaml.load(yamlString)
 }
 
-export const writeYaml = async (filePath, jsonObject): Promise<void> => {
+export const writeYaml = async (filePath: string, yamlContent: string): Promise<void> => {
+  await fs.writeFile(filePath, yamlContent, "utf8")
+}
+
+export const writeYamlFromJson = async (filePath, jsonObject): Promise<void> => {
   const yamlString = yaml.dump(jsonObject)
   await fs.writeFile(filePath, yamlString, "utf8")
 }