ShellHub OpenAPI for Community, Cloud and Enterprise
## How it works?
It is simples; When ShellHub is in developement mode (with the `SHELLHUB_ENV`
set to `development`), it will enable, through the `gateway`, a [URL to preview the
OpenAPI](http://localhost/openapi/) in any OpenAPI file after a page reload.
## How to use?
### Preview
Its usage is simple too, you just need `up` the `shellhub-io/shellhub` containers in development
mode and access the URL.
- Access the URL [http://localhost/openapi/](http://localhost/openapi/) to check the preview.
### Full spec vs customer docs
There are two builds of every edition spec, from the same source:
- **Full spec** — the internal source of truth, documenting every route (public,
internal, and admin). It backs the frontend client generation and the
dev-mode response validator. This is what the preview above serves.
- **Customer docs** — the published, customer-facing documentation. A
`drop-non-customer` decorator (`plugins/customer-filter.js`) keeps only the
namespace-scoped, API-key usable surface: it drops `/admin` and `/internal`
routes, operations that do not accept an API key, and anything flagged
`x-internal: true`; it also strips the `jwt` scheme so the docs show api-key
only. These are the `*-customer` API entries in `redocly.yaml`, published on
release by `openapi-cd.yml`.
Preview the customer docs locally at
[http://localhost/openapi/customer.html](http://localhost/openapi/customer.html).
### Lint
You can also linter the OpenAPI instances to check if everything is correct. You just need to run
the script called `lint` inside `scripts` folder.
```bash
Lint the OpenAPI instances.
Usage:
./scripts/lint
Instances:
community Lint the community instance
cloud Lint the cloud instance
enterprise Lint the enterprise instance
Options:
--help Display this help message
```
### Mock
If you need to mock a ShellHub instance, the `scripts` folder has another one called `mock`,
what will to make available a full service to you test the API based on instance you chose in
[http://localhost/openapi/mock](http://localhost/openapi/mock).
```bash
Mock the OpenAPI instances.
Usage:
./scripts/mock
Instances:
community Mock the community instance
cloud Mock the cloud instance
enterprise Mock the enterprise instance
Options:
--help Display this help message
```
### Proxy
If you need to check if the API contract is right, you can use the script called `proxy`,
what will to make available a full service to you send request to the API based on instance
you chose in [http://localhost/openapi/proxy](http://localhost/openapi/proxy).
```bash
Proxy the OpenAPI instances.
Usage:
./scripts/proxy
Instances:
community Proxy the community instance
cloud Proxy the cloud instance
enterprise Proxy the enterprise instance
Options:
--help Display this help message
```
### Generate
You can generate a TypeScript client from the OpenAPI specification for any of the available instances using the
generate script. This will build the client and place it in the specified output directory.
```bash
Generate the TypeScript client.
Usage:
./scripts/generate
Options:
--help Display this help message
```
For example, to generate a client in the `../shellhub/ui/src/api/client/` directory, you would run:
```bash
./scripts/generate ../shellhub/ui/src/api/client/
```
The TypeScript client will be generated in the specified folder and can be used to interact with the ShellHub API.
## Integrations
### Community
Today, the Community has a script called `openapi` to execute commands against the OpenAPI
spec provided by ShellHub `gateway` and this repository.
. . .