## What
Updates `@redocly/cli` to v1.7. This resolves the bug of TypeScript and tsx code samples in the OAS being generated as undefined files (see files under `www/apps/api-reference/specs/admin/code_samples/tsx` and `www/apps/api-reference/specs/store/code_samples/tsx`
I avoided re-generating OAS so that this PR doesn't have a huge diff. When the next release is out, an automated PR will be opened to update the OAS files, replacing the undefined files with `.tsx` files.
### Other Changes
- Small fixes to `medusa-oas-cli` README for clarity
## 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.
## What
Allow `medusa-oas` CLI to generate API client code from an OAS json file.
## Why
Manually maintaining API clients is time consuming and error prone. We wish to automate the process by using code generation strategies.
We also wish to eliminate direct import from `@medusajs/medusa` in clients which can lead to unwanted side effects like importing unnecessary dependencies.
## How
Fork and customize an OAS code generator library that is TypeScript friendly.
Attempt to match the interface and signature of our current client packages: `@medusajs/medusa-js`, `medusa-react`
Add a new `client` command to the `medusa-oas` CLI as the main interface to interact with the code generation tooling.
## Test
### Prerequisites
* From the root of the monorepo:
* `yarn install`
* `yarn build`
### Case - all in one build
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-store --type store`
* Expect `~/tmp/client-store` to contain the following files and directories:
```
core/
hooks/
models/
services/
index.ts
MedusaStore.ts
useMedusaStore.tsx
```
### Case - types only
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-types --type store --component types`
* Expect `~/tmp/client-types` to contain the following files and directories:
```
models/
index.ts
```
### Case - client only
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-only --type store --component client --types-package @medusajs/client-types`
* Expect `~/tmp/client-only` to contain the following files and directories:
```
core/
services/
index.ts
MedusaStore.ts
```
## 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`.
