feat(medusa-oas-cli,oas-github-ci): new options + added download of OAS in api reference (#5453)

.changeset/yellow-pillows-cry.md

@@ -0,0 +1,7 @@
+---
+"@medusajs/medusa-oas-cli": patch
+"@medusajs/oas-github-ci": patch
+---
+
+feat(medusa-oas-cli): Added `--main-file-name` option to specify output file name
+feat(oas-github-ci): Added `--with-full-file"` option to output both split and full files

package.json

@@ -70,7 +70,7 @@
     "test:integration:api": "turbo run test:integration --no-daemon --filter=integration-tests-api",
     "test:integration:plugins": "turbo run test:integration --no-daemon --filter=integration-tests-plugins",
     "test:integration:repositories": "turbo run test:integration --no-daemon --filter=integration-tests-repositories",
-    "openapi:generate": "yarn ./packages/oas/oas-github-ci run ci",
+    "openapi:generate": "yarn ./packages/oas/oas-github-ci run ci --with-full-file",
     "medusa-oas": "yarn ./packages/oas/medusa-oas-cli run medusa-oas",
     "release:snapshot": "changeset publish --no-git-tags --snapshot --tag snapshot",
     "develop": "ts-node --transpile-only ./integration-tests/development/server.js",

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

@@ -59,6 +59,10 @@ export const commandOptions: Option[] = [
     "--html",
     "Generate a static HTML using Redocly's build-docs command."
   ),
+  new Option(
+    "--main-file-name <mainFileName>",
+    "The name of the main YAML file."
+  ).default("openapi.yaml")
 ]
 
 export function getCommand(): Command {
@@ -95,7 +99,6 @@ export async function execute(cliParams: OptionValues): Promise<void> {
       throw new Error(`--config must be a file - ${configFileCustom}`)
     }
     if (![".json", ".yaml"].includes(path.extname(configFileCustom))) {
-      console.log(path.extname(configFileCustom))
       throw new Error(
         `--config file must be of type .json or .yaml - ${configFileCustom}`
       )
@@ -110,7 +113,7 @@ export async function execute(cliParams: OptionValues): Promise<void> {
   const tmpDir = await getTmpDirectory()
   const configTmpFile = path.resolve(tmpDir, "redocly-config.yaml")
   /** matches naming convention from `redocly split` */
-  const finalOASFile = path.resolve(outDir, "openapi.yaml")
+  const finalOASFile = cliParams.mainFileName
 
   await createTmpConfig(configFileDefault, configTmpFile)
   if (configFileCustom) {
@@ -143,7 +146,7 @@ export async function execute(cliParams: OptionValues): Promise<void> {
   if (shouldSplit) {
     await generateReference(srcFileSanitized, outDir)
   } else {
-    await jsonFileToYamlFile(srcFileSanitized, finalOASFile)
+    await jsonFileToYamlFile(srcFileSanitized, path.join(outDir, finalOASFile))
   }
   if (shouldBuildHTML) {
     const outHTMLFile = path.resolve(outDir, "index.html")

packages/oas/oas-github-ci/scripts/build-openapi.js

@@ -6,6 +6,7 @@ const path = require("path")
 const execa = require("execa")
 
 const isDryRun = process.argv.indexOf("--dry-run") !== -1
+const withFullFile = process.argv.indexOf("--with-full-file") !== -1
 const basePath = path.resolve(__dirname, `../`)
 const repoRootPath = path.resolve(basePath, `../../../`)
 const docsApiPath = path.resolve(repoRootPath, "www/apps/api-reference/specs")
@@ -30,7 +31,7 @@ const generateOASSource = async (outDir, apiType) => {
 }
 
 const generateDocs = async (srcFile, outDir, isDryRun) => {
-  const params = [
+  let params = [
     "docs",
     `--src-file=${srcFile}`,
     `--out-dir=${outDir}`,
@@ -40,6 +41,21 @@ const generateDocs = async (srcFile, outDir, isDryRun) => {
   if (isDryRun) {
     params.push("--dry-run")
   }
+  await runMedusaOasCommand(params)
+  if (withFullFile && !isDryRun) {
+    console.log("Generating full file...")
+    params = [
+      "docs",
+      `--src-file=${srcFile}`,
+      `--out-dir=${outDir}`,
+      `--main-file-name=openapi.full.yaml`
+    ]
+    await runMedusaOasCommand(params)
+    console.log("Finished generating full file.")
+  }
+}
+
+const runMedusaOasCommand = async (params) => {
   const { all: logs } = await execa("medusa-oas", params, {
     cwd: basePath,
     all: true,

www/apps/api-reference/app/_mdx/client-libraries.mdx

@@ -1,5 +1,6 @@
 import { CodeTabs } from "docs-ui"
 import Space from "@/components/Space"
+import DownloadFull from "@/components/DownloadFull"
 
 ### Just Getting Started?
 
@@ -28,4 +29,10 @@ Check out the [quickstart guide](https://docs.medusajs.com/create-medusa-app).
       }
     }
   ]}
-/>
+/>
+
+### Download Full Reference
+
+Download this reference as an OpenApi YAML file. You can import this file to tools like Postman and start sending requests directly to your Medusa backend.
+
+<DownloadFull />

www/apps/api-reference/app/api/download/[area]/route.ts

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from "fs"
+import { NextResponse } from "next/server"
+import path from "path"
+
+type DownloadParams = {
+  params: {
+    area: string
+  }
+}
+
+export function GET(request: Request, { params }: DownloadParams) {
+  const { area } = params
+  const filePath = path.join(process.cwd(), `specs/${area}/openapi.full.yaml`)
+
+  if (!existsSync(filePath)) {
+    return new NextResponse(null, {
+      status: 404,
+    })
+  }
+
+  const fileContent = readFileSync(filePath)
+
+  return new Response(fileContent, {
+    headers: {
+      "Content-Type": "application/x-yaml",
+      "Content-Disposition": `attachment; filename="openapi.yaml"`,
+    },
+  })
+}

www/apps/api-reference/components/DownloadFull/index.tsx

@@ -0,0 +1,19 @@
+"use client"
+
+import { Button } from "docs-ui"
+import { useArea } from "../../providers/area"
+import Link from "next/link"
+
+const DownloadFull = () => {
+  const { area } = useArea()
+
+  return (
+    <Button variant="secondary">
+      <Link href={`/api/download/${area}`} download target="_blank">
+        Download openapi.yaml
+      </Link>
+    </Button>
+  )
+}
+
+export default DownloadFull