53532df8d5
### What
Add OAS build step to patch known circular references that prevent Redocly from rendering the API documentation.
### Why
We've encountered crashing and loading issues with Redocly when the OAS contained circular references. We have been working around the limitation by omitting some known problematic $ref in our source OAS. We wish to move away from this strategy in order to always explicitly include $ref in our OAS.
### How
We are introducing a custom Redocly CLI plugin that will replace `$ref` by `type: object` base on a configurable set of instructions. These instructions can be modified in `docs-util/redocly/config.yaml`
We are adding a `redocly bundle` step in the current OAS build process in order to sanitize problematic circular references.
We updated the redocly-cli package version in order to ensure that plugins are supported.
### Test
We will use [Cart.payment](fd5c185159/packages/medusa/src/models/cart.ts (L72-L74)) to ensure that the new process is properly sanitizing.
* Run `yarn openapi:generate`
* Open `docs/api/store/components/schemas/Cart.yaml`
* Expect the `payment` property to have been sanitized to `type: object`
* Run `yarn redocly preview-docs docs/api/store/openapi.yaml --config=docs-util/redocly/config.yaml`
* Visit http://127.0.0.1:8080/#tag/Cart/operation/GetCartsCart
* In the response, expect cart.payment to not list the properties of the Payment schema.
152 lines
3.7 KiB
JavaScript
Executable File
152 lines
3.7 KiB
JavaScript
Executable File
#!/usr/bin/env node
|
|
|
|
const fs = require("fs")
|
|
const OAS = require("oas-normalize")
|
|
const swaggerInline = require("swagger-inline")
|
|
const { exec } = require("child_process")
|
|
|
|
const isDryRun = process.argv.indexOf("--dry-run") !== -1
|
|
|
|
// Storefront API
|
|
swaggerInline(
|
|
[
|
|
"./packages/medusa/src/models",
|
|
"./packages/medusa/src/types",
|
|
"./packages/medusa/src/api/middlewares",
|
|
"./packages/medusa/src/api/routes/store",
|
|
],
|
|
{
|
|
base: "./docs/api/store-spec3-base.yaml",
|
|
}
|
|
)
|
|
.then((gen) => {
|
|
const oas = new OAS(gen)
|
|
oas
|
|
.validate(true)
|
|
.then(() => {
|
|
if (!isDryRun) {
|
|
fs.writeFileSync("./docs/api/store-spec3.json", gen)
|
|
}
|
|
})
|
|
.catch((err) => {
|
|
console.log("Error in store")
|
|
console.error(err)
|
|
process.exit(1)
|
|
})
|
|
})
|
|
.catch((err) => {
|
|
console.log("Error in store")
|
|
console.error(err)
|
|
process.exit(1)
|
|
})
|
|
|
|
swaggerInline(
|
|
[
|
|
"./packages/medusa/src/models",
|
|
"./packages/medusa/src/types",
|
|
"./packages/medusa/src/api/middlewares",
|
|
"./packages/medusa/src/api/routes/store",
|
|
],
|
|
{
|
|
base: "./docs/api/store-spec3-base.yaml",
|
|
format: "yaml",
|
|
}
|
|
)
|
|
.then((gen) => {
|
|
if (!isDryRun) {
|
|
fs.writeFileSync("./docs/api/store-spec3.yaml", gen)
|
|
exec(
|
|
[
|
|
"rm -rf docs/api/store/",
|
|
"yarn run -- redocly bundle docs/api/store-spec3.yaml -o docs/api/store-spec3.yaml --config=docs-util/redocly/config.yaml",
|
|
"yarn run -- redocly split docs/api/store-spec3.yaml --outDir=docs/api/store/",
|
|
].join(" && "),
|
|
(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")
|
|
}
|
|
})
|
|
.catch((err) => {
|
|
console.log("Error in store")
|
|
console.error(err)
|
|
process.exit(1)
|
|
})
|
|
|
|
// Admin API
|
|
swaggerInline(
|
|
[
|
|
"./packages/medusa/src/models",
|
|
"./packages/medusa/src/types",
|
|
"./packages/medusa/src/api/middlewares",
|
|
"./packages/medusa/src/api/routes/admin",
|
|
],
|
|
{
|
|
base: "./docs/api/admin-spec3-base.yaml",
|
|
}
|
|
)
|
|
.then((gen) => {
|
|
const oas = new OAS(gen)
|
|
oas
|
|
.validate(true)
|
|
.then(() => {
|
|
if (!isDryRun) {
|
|
fs.writeFileSync("./docs/api/admin-spec3.json", gen)
|
|
}
|
|
})
|
|
.catch((err) => {
|
|
console.log("Error in admin")
|
|
console.error(err)
|
|
process.exit(1)
|
|
})
|
|
})
|
|
.catch((err) => {
|
|
console.log("Error in admin")
|
|
console.error(err)
|
|
process.exit(1)
|
|
})
|
|
|
|
swaggerInline(
|
|
[
|
|
"./packages/medusa/src/models",
|
|
"./packages/medusa/src/types",
|
|
"./packages/medusa/src/api/middlewares",
|
|
"./packages/medusa/src/api/routes/admin",
|
|
],
|
|
{
|
|
base: "./docs/api/admin-spec3-base.yaml",
|
|
format: "yaml",
|
|
}
|
|
)
|
|
.then((gen) => {
|
|
if (!isDryRun) {
|
|
fs.writeFileSync("./docs/api/admin-spec3.yaml", gen)
|
|
exec(
|
|
[
|
|
"rm -rf docs/api/admin/",
|
|
"yarn run -- redocly bundle docs/api/admin-spec3.yaml -o docs/api/admin-spec3.yaml --config=docs-util/redocly/config.yaml",
|
|
"yarn run -- redocly split docs/api/admin-spec3.yaml --outDir=docs/api/admin/",
|
|
].join(" && "),
|
|
(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")
|
|
}
|
|
})
|
|
.catch((err) => {
|
|
console.log("Error in admin")
|
|
console.error(err)
|
|
process.exit(1)
|
|
})
|