Patrick
1456056e8f
## What New `medusa-oas docs` to improve OAS compatibility with for Redocly API documentation viewer and handle deep circular references. ## Why We wish to share the tooling we have been using to generate our public API documentation. ## How * Move `/docs-utils/redocly` under `medusa-oas-cli` package. * Move some of the operations from `oas-github-ci/scripts/build-openapi.js` under the `medusa-oas docs` command. * Improve DevX when dealing with circular references by outputting precise troubleshooting recommendations in the error message. * Extract some common operations in utility methods. ## Tests ### Step 1 * Run `yarn install` * Run `yarn build` * Run `yarn openapi:generate --dry-run` * Expect same behaviour as before where OAS is validated and circular references are checked. ### Step 2 * Run `yarn openapi:generate` * Expect same behaviour as before where API documentation is generated in `/docs` ### Step 3 * Move to the `packages/oas/medusa-oas-cli` * Run `yarn medusa-oas oas --type store --out-dir ~/tmp/oas` to generate the raw OAS file. * Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --preview` * Open url from the console output in a browser * Expect a preview of the API documentation using Redocly. ### Step 4 * Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/docs/store --clean --split` * Expect a similiar output as `yarn openapi:generate` ### Step 5 * Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/docs/store --clean --html` * Expect `index.html` to have been created. * Run `npx http-server ~/tmp/docs/store -p 8000` * Open http://127.0.0.1:8000 in a browser. * Expect a zero-dependency static rendering of the API documentation using Redocly. ### Step 6 * To emulate an unhandled circular reference, edit [packages/oas/medusa-oas-cli/redocly/redocly-config.yaml](https://github.com/medusajs/medusa/blob/d180f47e1609e74f46f72cdeef6265a654da3e7e/packages/oas/medusa-oas-cli/redocly/redocly-config.yaml#L9-L10) and comment out "Address: - Customer" * Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --dry-run` * Expect an error message with a hint on how to resolve the issue. * Create a file `~/tmp/redocly-config.yaml` and paste in the recommendation from the error message. * Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --dry-run --config ~/tmp/redocly-config.yaml` * Expect Dry run to succeed.
66 lines
1.6 KiB
JavaScript
Executable File
66 lines
1.6 KiB
JavaScript
Executable File
#!/usr/bin/env node
|
|
|
|
const fs = require("fs/promises")
|
|
const os = require("os")
|
|
const path = require("path")
|
|
const execa = require("execa")
|
|
|
|
const isDryRun = process.argv.indexOf("--dry-run") !== -1
|
|
const basePath = path.resolve(__dirname, `../`)
|
|
const repoRootPath = path.resolve(basePath, `../../../`)
|
|
const docsApiPath = path.resolve(repoRootPath, "docs/api/")
|
|
|
|
const run = async () => {
|
|
const oasOutDir = isDryRun ? await getTmpDirectory() : docsApiPath
|
|
for (const apiType of ["store", "admin"]) {
|
|
await generateOASSource(oasOutDir, apiType)
|
|
const oasSrcFile = path.resolve(oasOutDir, `${apiType}.oas.json`)
|
|
const docsOutDir = path.resolve(oasOutDir, apiType)
|
|
await generateDocs(oasSrcFile, docsOutDir, isDryRun)
|
|
}
|
|
}
|
|
|
|
const generateOASSource = async (outDir, apiType) => {
|
|
const { all: logs } = await execa(
|
|
"medusa-oas",
|
|
["oas", `--type=${apiType}`, `--out-dir=${outDir}`],
|
|
{ cwd: basePath, all: true }
|
|
)
|
|
console.log(logs)
|
|
}
|
|
|
|
const generateDocs = async (srcFile, outDir, isDryRun) => {
|
|
const params = [
|
|
"docs",
|
|
`--src-file=${srcFile}`,
|
|
`--out-dir=${outDir}`,
|
|
`--clean`,
|
|
`--split`,
|
|
]
|
|
if (isDryRun) {
|
|
params.push("--dry-run")
|
|
}
|
|
const { all: logs } = await execa("medusa-oas", params, {
|
|
cwd: basePath,
|
|
all: true,
|
|
})
|
|
console.log(logs)
|
|
}
|
|
|
|
const getTmpDirectory = async () => {
|
|
/**
|
|
* RUNNER_TEMP: GitHub action, the path to a temporary directory on the runner.
|
|
*/
|
|
const tmpDir = process.env["RUNNER_TEMP"] ?? os.tmpdir()
|
|
return await fs.mkdtemp(tmpDir)
|
|
}
|
|
|
|
void (async () => {
|
|
try {
|
|
await run()
|
|
} catch (err) {
|
|
console.log(err)
|
|
process.exit(1)
|
|
}
|
|
})()
|