1456056e8f
## 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.
220 lines
4.5 KiB
Markdown
220 lines
4.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
yarn medusa-oas <command>
|
|
```
|
|
|
|
---
|
|
|
|
### Command - `oas`
|
|
|
|
This command will scan the `@medusajs/medusa` package in order to extract JSDoc OAS into a json file.
|
|
|
|
The command will output one of three the files `admin.oas.json`, `store.oas.json` or `combined.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 `admin`, `store`, `combined`.
|
|
|
|
The `combined` option will merge both the admin and the store APIs into a single OAS file.
|
|
|
|
```bash
|
|
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 `./`.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
yarn medusa-oas oas --paths ~/medusa-server/src
|
|
```
|
|
|
|
#### `--base <path>`
|
|
|
|
Allows overwriting the content the API's base.yaml OAS that is fed to swagger-inline.
|
|
Paths, tags, and components will be merged together. Other OAS properties will be overwritten.
|
|
|
|
```bash
|
|
yarn medusa-oas oas --base ~/medusa-server/oas/custom.oas.base.yaml
|
|
```
|
|
|
|
#### `--dry-run`
|
|
|
|
Will package the OAS but will not output file. Useful for validating OAS.
|
|
|
|
```bash
|
|
yarn medusa-oas oas --dry-run
|
|
```
|
|
|
|
#### `--force`
|
|
|
|
Ignore OAS errors and attempt to output generated OAS files.
|
|
|
|
```bash
|
|
yarn medusa-oas oas --force
|
|
```
|
|
|
|
---
|
|
|
|
### Command - `client`
|
|
|
|
Will generate API client files from a given OAS file.
|
|
|
|
#### `--src-file <path>`
|
|
|
|
Specify the path to the OAS JSON file.
|
|
|
|
```bash
|
|
yarn medusa-oas client --src-file ./store.oas.json`
|
|
```
|
|
|
|
#### `--name <name>`
|
|
|
|
Namespace for the generated client. Usually `admin` or `store`.
|
|
|
|
```bash
|
|
yarn medusa-oas client --name admin`
|
|
```
|
|
|
|
#### `--out-dir <path>`
|
|
|
|
Specify in which directory should the files be outputted. Accepts relative and absolute path.
|
|
If the directory doesn't exist, it will be created. Defaults to `./`.
|
|
|
|
```bash
|
|
yarn medusa-oas client --out-dir ./client`
|
|
```
|
|
|
|
#### `--type <type>`
|
|
|
|
Client component types to generate. Accepts `all`, `types`, `client`, `hooks`.
|
|
Defaults to `all`.
|
|
|
|
```bash
|
|
yarn medusa-oas client --type types`
|
|
```
|
|
|
|
#### `--types-packages <name>`
|
|
|
|
Replace relative import statements by types package name. Mandatory when using `--type client` or `--type hooks`.
|
|
|
|
```bash
|
|
yarn medusa-oas client --types-packages @medusajs/client-types`
|
|
```
|
|
|
|
#### `--client-packages <name>`
|
|
|
|
Replace relative import statements by client package name. Mandatory when using `--type hooks`.
|
|
|
|
```bash
|
|
yarn medusa-oas client --client-packages @medusajs/medusa-js`
|
|
```
|
|
|
|
#### `--clean`
|
|
|
|
Delete destination directory content before generating client.
|
|
|
|
```bash
|
|
yarn medusa-oas client --clean
|
|
```
|
|
|
|
---
|
|
|
|
### Command - `docs`
|
|
|
|
Will sanitize OAS for use with Redocly's API documentation viewer.
|
|
|
|
#### `--src-file <path>`
|
|
|
|
Specify the path to the OAS JSON file.
|
|
|
|
```bash
|
|
yarm medusa-oas docs --src-file ./store.oas.json
|
|
```
|
|
|
|
#### `--out-dir <path>`
|
|
|
|
Specify in which directory should the files be outputted. Accepts relative and absolute path.
|
|
If the directory doesn't exist, it will be created. Defaults to `./`.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --out-dir ./docs`
|
|
```
|
|
|
|
#### `--config <path>`
|
|
|
|
Specify the path to a Redocly config file.
|
|
|
|
```bash
|
|
yarn medusa-oas --config ./redocly-config.yaml
|
|
```
|
|
|
|
#### `--dry-run`
|
|
|
|
Will sanitize the OAS but will not output file. Useful for troubleshooting circular reference issues.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --dry-run
|
|
```
|
|
|
|
#### `--clean`
|
|
|
|
Delete destination directory content before generating client.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --clean
|
|
```
|
|
|
|
#### `--split`
|
|
|
|
Creates a multi-file structure output. Uses `redocly split` internally.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --split
|
|
```
|
|
|
|
#### `--preview`
|
|
|
|
Generate a preview of the API documentation in a browser. Does not output files. Uses `redocly preview-docs` internally.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --preview
|
|
```
|
|
|
|
#### `--html`
|
|
|
|
Generate a zero-dependency static HTML file. Uses `redocly build-docs` internally.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --html
|
|
```
|