Patrick
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](https://github.com/medusajs/medusa/blob/0adb0d9ff96087613b7a634cbc97a7e301b01121/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`.
medusa-oas-cli - 0.1.0 - experimental
A command-line tool for all OpenAPI Specifications (OAS) related tooling.
Install
yarn add --dev @medusajs/medusa-oas-cli
Install in the global namespace is not yet supported.
npm install -g @medusajs/medusa-oas-cli
Configuration / First time setup
N/A
How to use
yarn medusa-oas <command>
Command - oas
This command will scan the @medusajs/medusa package in order to extract JSDoc OAS into a json file.
By default, the command will output the two files admin.oas.json and store.oas.json in the same directory that the
command was run.
Invalid OAS with throw an error and will prevent the files from being outputted.
--type <string>
Specify which API OAS to create. Accepts all, admin, store.
Defaults to all.
yarn medusa-oas oas --type admin
--out-dir <path>
Specify in which directory should the files be outputted. It accepts a relative or absolute path.
If the directory doesn't exist, it will be created. Defaults to ./.
yarm medusa-oas oas --out-dir
--paths <paths...>
Allows passing additional directory paths to crawl for JSDoc OAS and include in the generated OAS. It accepts multiple entries.
yarn medusa-oas oas --paths ~/medusa-server/src
--dry-run
Will package the OAS but will not output file. Useful for validating OAS.
yarn medusa-oas oas --dry-run
--force
Ignore OAS errors and attempt to output generated OAS files.
yarn medusa-oas oas --force