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.
98 lines
1.9 KiB
YAML
98 lines
1.9 KiB
YAML
plugins:
|
|
- "./plugins/plugin.js"
|
|
|
|
# Allows to replace a $ref with `type: object` in order to avoid infinite loops
|
|
# when Redocly attempts to render circular references.
|
|
decorators:
|
|
plugin/circular-patch:
|
|
verbose: true
|
|
schemas:
|
|
Address:
|
|
- Customer
|
|
Cart:
|
|
- Customer
|
|
- Order
|
|
- Payment
|
|
ClaimItem:
|
|
- ClaimOrder
|
|
ClaimOrder:
|
|
- Fulfillment
|
|
- Order
|
|
- Return
|
|
Customer:
|
|
- Order
|
|
DraftOrder:
|
|
- Cart
|
|
- Order
|
|
Fulfillment:
|
|
- ClaimOrder
|
|
- Order
|
|
- Swap
|
|
GiftCard:
|
|
- Order
|
|
GiftCardTransaction:
|
|
- GiftCard
|
|
- Order
|
|
LineItem:
|
|
- Cart
|
|
- ClaimOrder
|
|
- Order
|
|
- OrderEdit
|
|
- Swap
|
|
Order:
|
|
- Cart
|
|
- ClaimOrder
|
|
- Customer
|
|
- DraftOrder
|
|
- Fulfillment
|
|
- OrderEdit
|
|
- Payment
|
|
- Refund
|
|
- Return
|
|
- Swap
|
|
OrderEdit:
|
|
- Order
|
|
Payment:
|
|
- Cart
|
|
- Order
|
|
- Swap
|
|
Refund:
|
|
- Order
|
|
- Payment
|
|
Return:
|
|
- ClaimOrder
|
|
- Order
|
|
- Swap
|
|
ShippingMethod:
|
|
- Cart
|
|
- ClaimOrder
|
|
- Order
|
|
- Payment
|
|
- Return
|
|
- Swap
|
|
Swap:
|
|
- Cart
|
|
- Fulfillment
|
|
- Order
|
|
- Payment
|
|
- Return
|
|
|
|
# Similar config to /www/docs/docusaurus.config.js > redocusaurus
|
|
# Allows to emulate rendering of API public documentation when using `yarn redocly preview-docs openapi.yaml`
|
|
theme.openapi:
|
|
theme:
|
|
colors:
|
|
primary:
|
|
dart: "#242526"
|
|
sidebar:
|
|
width: "250px"
|
|
disableSearch: true
|
|
expandResponses: "200,204"
|
|
generatedPayloadSamplesMaxDepth: 4
|
|
hideDownloadButton: true
|
|
hideRequestPayloadSample: true
|
|
nativeScrollbars: true
|
|
requiredPropsFirst: true
|
|
showObjectSchemaExamples: true
|
|
sortTagsAlphabetically: true
|