feat(OAS): sanitize circular reference for Redocly (#3198)
### 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](https://github.com/medusajs/medusa/blob/fd5c18515931aca7cb5d29530f5dd03ebaf7e07e/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.
This commit is contained in:
@@ -0,0 +1,14 @@
|
||||
const CircularPatch = require("./decorators/circular-patch")
|
||||
|
||||
const id = "plugin"
|
||||
|
||||
const decorators = {
|
||||
oas3: {
|
||||
"circular-patch": CircularPatch,
|
||||
},
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
id,
|
||||
decorators,
|
||||
}
|
||||
Reference in New Issue
Block a user