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](d180f47e16/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)
|
|
}
|
|
})()
|