8137061908
## What
Introduce a CLI for extracting OAS from the core `medusa` package.
## Why
We need to decouple OAS tooling from documentation tooling in order to allow packages and external systems to leverage our OAS has a dependency.
## How
Introduce a new OAS workspace within packages in order to organize current and future OAS related package. Only 1 OAS package for now.
Introduce a new CLI only package to act as the main gateway for all upcoming OAS tooling. Only 1 command for now.
Update documentation tooling pertaining to OAS to use the CLI instead.
## Test
### Prerequisite
From the monorepo root:
* `yarn install`
* `yarn build`
### Documentation
#### Case - validation only - success
* Run `yarn openapi:generate --dry-run`
* Expect console output `🟢 Valid OAS` but no mention of `🔵 Exported OAS`
#### Case - validation only - invalid
* Introduce a bug by renaming `@schema Cart` to `@schema Kart` in [models/cart.ts](0adb0d9ff9/packages/medusa/src/models/cart.ts (L2))
* Run `yarn build` to update `@medusajs/medusa` package with the bug.
* Run `yarn openapi:generate --dry-run`
* Expect console output `🔴 Invalid OAS` with a stack trace of the issue.
#### Case - docs generation
* Run `yarn openapi:generate`
* Expect `docs/api/` directory to contain:
* `admin.oas.json` (raw OAS)
* `store.oas.json` (raw OAS)
* `admin.oas.yaml` (sanitized OAS)
* `store.oas.yaml` (sanitized OAS)
* `admin/` (updated redocly split output)
* `store/` (updated redocly split output)
### CLI
#### Case - crawl additional paths
* From a local medusa server (`medusa-starter-default`), add an `index.ts` file in `src/models/`
* In the `index.ts`, add dummy OAS JSDoc like `/** @schema Foobar */`
* From the root of the monorepo, run `yarn medusa-oas --type store --paths path-to-medusa-server/src`
* Expect a `store.oas.json` to be created at the root of the monorepo.
* The `store.oas.json` should contain an additional `Foobar` entry in `components.schemas`.
157 lines
3.2 KiB
YAML
157 lines
3.2 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: false
|
|
schemas:
|
|
Address:
|
|
- Customer
|
|
Cart:
|
|
- Customer
|
|
- Order
|
|
- Payment
|
|
- PaymentSession
|
|
ClaimImage:
|
|
- ClaimItem
|
|
ClaimItem:
|
|
- ClaimOrder
|
|
ClaimOrder:
|
|
- Fulfillment
|
|
- Order
|
|
- Return
|
|
Country:
|
|
- Region
|
|
Customer:
|
|
- Order
|
|
CustomerGroup:
|
|
- Customer
|
|
- PriceList
|
|
Discount:
|
|
- Discount
|
|
DiscountRule:
|
|
- DiscountCondition
|
|
DraftOrder:
|
|
- Cart
|
|
- Order
|
|
Fulfillment:
|
|
- ClaimOrder
|
|
- Order
|
|
- Swap
|
|
FulfillmentItem:
|
|
- Fulfillment
|
|
GiftCard:
|
|
- Order
|
|
GiftCardTransaction:
|
|
- GiftCard
|
|
- Order
|
|
LineItem:
|
|
- Cart
|
|
- ClaimOrder
|
|
- Order
|
|
- OrderEdit
|
|
- Swap
|
|
LineItemAdjustment:
|
|
- LineItem
|
|
LineItemTaxLine:
|
|
- LineItem
|
|
MoneyAmount:
|
|
- PriceList
|
|
- ProductVariant
|
|
- Region
|
|
Notification:
|
|
- Notification
|
|
Order:
|
|
- Cart
|
|
- ClaimOrder
|
|
- Customer
|
|
- DraftOrder
|
|
- Fulfillment
|
|
- OrderEdit
|
|
- Payment
|
|
- Refund
|
|
- Return
|
|
- Swap
|
|
OrderEdit:
|
|
- Order
|
|
OrderItemChange:
|
|
- OrderEdit
|
|
Payment:
|
|
- Cart
|
|
- Order
|
|
- Swap
|
|
ProductCategory:
|
|
- ProductCategory
|
|
- Product
|
|
ProductCollection:
|
|
- Product
|
|
ProductOption:
|
|
- Product
|
|
ProductOptionValue:
|
|
- ProductOption
|
|
- ProductVariant
|
|
ProductVariant:
|
|
- Product
|
|
ProductVariantInventoryItem:
|
|
- ProductVariant
|
|
Refund:
|
|
- Order
|
|
- Payment
|
|
Return:
|
|
- ClaimOrder
|
|
- Order
|
|
- Swap
|
|
ReturnItem:
|
|
- Return
|
|
ReturnReason:
|
|
- ReturnReason
|
|
SalesChannelLocation:
|
|
- SalesChannel
|
|
ShippingMethod:
|
|
- Cart
|
|
- ClaimOrder
|
|
- Order
|
|
- Payment
|
|
- Return
|
|
- Swap
|
|
ShippingMethodTaxLine:
|
|
- ShippingMethod
|
|
ShippingOption:
|
|
- Region
|
|
ShippingOptionRequirement:
|
|
- ShippingOption
|
|
ShippingProfile:
|
|
- Product
|
|
- ShippingOption
|
|
Swap:
|
|
- Cart
|
|
- Fulfillment
|
|
- Order
|
|
- Payment
|
|
- Return
|
|
TaxRate:
|
|
- Region
|
|
TrackingLink:
|
|
- Fulfillment
|
|
|
|
# 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
|