@skriptfabrik/elements-cli
Version:
The missing CLI for beautiful, interactive API docs powered by with Stoplight Elements
158 lines (113 loc) • 6.41 kB
Markdown
# Elements CLI
[](https://www.npmjs.com/package/@skriptfabrik/elements-cli)
[](https://www.npmjs.com/package/@skriptfabrik/elements-cli)
[](https://github.com/skriptfabrik/elements-cli/actions/workflows/ci.yml)
> The missing CLI for beautiful, interactive API docs powered by with [Stoplight Elements](https://github.com/stoplightio/elements)
## Installation
Install using [npm](https://docs.npmjs.com/about-npm/) as global package:
```bash
npm install -g @skriptfabrik/elements-cli
```
## Usage
```bash
elements --help
```
```text
Elements CLI
Usage:
elements command [options] [arguments]
Options:
-h, --help Display this help message
-v, --version Print version number
Commands:
export Export rendered API docs
preview Preview rendered API docs
```
### Export
```bash
elements export --help
```
```text
Elements CLI
Usage:
elements export [options] <openapi_json>
Arguments:
openapi_json The path or URL of the OpenAPI JSON file
Options:
--base-path=BASE_PATH Use the given base path [default: "/"]
--credentials-policy=CREDENTIALS_POLICY Credentials policy for "Try It" feature: omit, include, same-origin [default: "omit"]
--cors-proxy=CORS_PROXY Provide CORS proxy
-f, --filter-internal Filter out any content which has been marked as internal with x-internal
-h, --help Display this help message
--layout=LAYOUT Layout for Elements: sidebar, stacked [default: "sidebar"]
--logo=LOGO URL of an image that will show as a small square logo next to the title
-n --no-try-it Hide the "Try It" panel (the interactive API console)
--router=ROUTER Determines how navigation should work: history, hash, memory, static [default: "history"]
--style=STYLE Additional style for Elements [default: "flex: 1 0 0; overflow: hidden;"]
--title=TITLE API docs title [default: "My API Docs"]
--variable=VARIABLE Variable to be replaced in the OpenAPI document
-v, --version Print version number
Examples:
Export rendered API docs based on local openapi.json path as index.html:
elements export openapi.json > index.html
Export rendered Swagger Petstore docs based on remote https://petstore.swagger.io/v2/swagger.json URL as index.html:
elements export --title="Swagger Petstore" https://petstore.swagger.io/v2/swagger.json > index.html
```
### Preview
```bash
elements preview --help
```
```text
Elements CLI
Usage:
elements preview [options] <openapi_json>
Arguments:
openapi_json The path or URL of the OpenAPI JSON file
Options:
--base-path=BASE_PATH Use the given base path [default: "/"]
--credentials-policy=CREDENTIALS_POLICY Credentials policy for "Try It" feature: omit, include, same-origin [default: "omit"]
-c --with-cors-proxy Enable CORS proxy capabilities
-f, --filter-internal Filter out any content which has been marked as internal with x-internal
-h, --help Display this help message
--hostname=HOSTNAME Server hostname [default: "localhost"]
--layout=LAYOUT Layout for Elements: sidebar, stacked [default: "sidebar"]
--logo=LOGO URL of an image that will show as a small square logo next to the title
-n --no-try-it Hide the "Try It" panel (the interactive API console)
-p, --poll Use polling instead of file system events
--port=PORT Server port [default: 8000]
--router=ROUTER Determines how navigation should work: history, hash, memory, static [default: "history"]
--style=STYLE Additional style for Elements [default: "flex: 1 0 0; overflow: hidden;"]
--title=TITLE API docs title [default: "My API Docs"]
--variable=VARIABLE Variable to be replaced in the OpenAPI document
-v, --version Print version number
-w --watch Watch for changes and reload (only for local files)
--virtual-host=VIRTUAL_HOST Reported hostname [default: localhost]
--virtual-port=VIRTUAL_PORT Reported port [default: 8000]
--working-dir=PWD Use the given directory as working directory
Examples:
Preview rendered API docs based on local openapi.json path:
elements preview openapi.json
Preview rendered Swagger Petstore docs based on remote https://petstore.swagger.io/v2/swagger.json URL:
elements preview --title="Swagger Petstore" https://petstore.swagger.io/v2/swagger.json
Preview local API docs, enable CORS proxy and watch/reload on data changes:
elements preview -cw openapi.json
```
## Docker
### Export
Export rendered Swagger Petstore docs as `index.html`:
```bash
docker run --rm skriptfabrik/elements-cli export --title="Swagger Petstore" https://petstore.swagger.io/v2/swagger.json > index.html
```
### Preview
Use the following command to preview rendered API docs at `http://localhost:8080/` based on mounted `openapi.json` path:
```bash
docker run --rm -p 8000:8000 -v `pwd`:/data:ro skriptfabrik/elements-cli preview openapi.json
```
Preview rendered Swagger Petstore docs at `http://localhost:8080/` based on remote URL:
```bash
docker run --rm -p 8000:8000 skriptfabrik/elements-cli preview --title="Swagger Petstore" https://petstore.swagger.io/v2/swagger.json
```
Preview mounted API docs at `http://localhost:8080/`, enable CORS proxy capabilities and watch/reload on data changes:
```bash
docker run --rm -p 8000:8000 -v `pwd`:/data:ro skriptfabrik/elements-cli preview -cw openapi.json
```