78768574af
* chore: Remove generated client types folder * chore: Remove typescript-codegen package and client commands for oas
156 lines
3.4 KiB
Markdown
156 lines
3.4 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 - `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 --src-file ./store.oas.json --out-dir ./docs`
|
|
```
|
|
|
|
#### `--config <path>`
|
|
|
|
Specify the path to a Redocly config file.
|
|
|
|
```bash
|
|
yarn medusa-oas --src-file ./store.oas.json --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 --src-file ./store.oas.json --dry-run
|
|
```
|
|
|
|
#### `--clean`
|
|
|
|
Delete destination directory content before generating the docs.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --src-file ./store.oas.json --clean
|
|
```
|
|
|
|
#### `--split`
|
|
|
|
Creates a multi-file structure output. Uses `redocly split` internally.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --src-file ./store.oas.json --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 --src-file ../../../www/apps/api-reference/specs/store.oas.json --preview
|
|
```
|
|
|
|
#### `--html`
|
|
|
|
Generate a zero-dependency static HTML file. Uses `redocly build-docs` internally.
|
|
|
|
```bash
|
|
yarn medusa-oas docs --src-file ./store.oas.json --html
|
|
```
|