Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stackql/openapisaurus
Deno based openapi document utility for splitting openapi spec and generating stackql providers
https://github.com/stackql/openapisaurus
openapi rest sql stackql
Last synced: about 2 months ago
JSON representation
Deno based openapi document utility for splitting openapi spec and generating stackql providers
- Host: GitHub
- URL: https://github.com/stackql/openapisaurus
- Owner: stackql
- License: mit
- Created: 2023-03-07T21:20:38.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-30T01:28:37.000Z (2 months ago)
- Last Synced: 2024-10-30T08:58:16.740Z (2 months ago)
- Topics: openapi, rest, sql, stackql
- Language: TypeScript
- Homepage: https://stackql.io/
- Size: 7.18 MB
- Stars: 6
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# openapisaurus
> Command line utility to split OpenAPI documents into smaller, self contained, service oriented documents and prepare StackQL provider interfaces
> Command line utility to help developers prepare and submit StackQL provider specs, see [StackQL](https://github.com/stackql/stackql)
`openapisaurus` is implemented in TypeScript and designed to be run using the [`deno`](https://deno.land/) runtime.
## Installation
1. Install Deno by following the instructions at [deno.land](https://deno.land/).
2. Clone the `openapisaurus` repository to your local machine:
```
git clone [email protected]:stackql/openapisaurus.git
```
3. Make the `openapisaurus` script executable by running the following command:
```
chmod +x openapisaurus
```
## Command Line Usage
### `split`
Splits an OpenAPI spec into multiple service scoped documents.
> __Usage:__
> `openapisaurus split `
>
> __Arguments:__
> `apiDoc` __[REQUIRED]__ OpenAPI specification to be split.
>
> __Flags:__
> `--providerName` __[REQUIRED]__ Name of the provider.
> `--svcDiscriminator` __[REQUIRED]__ [JMESPath](https://jmespath.org/) expression to extract the service name from the OpenAPI spec.
> `--exclude` __[OPTIONAL]__ [JMESPath](https://jmespath.org/) expression for paths to exclude from processing.
> `--outputDir` __[OPTIONAL]__ Directory to write the output OpenAPI documents to. (defaults to `cwd`)
> `--overwrite` __[OPTIONAL]__ Overwrite existing files. (defaults to `false`)
> `--verbose` __[OPTIONAL]__ Verbose output (defaults to `false`).
#### Examples
`fivetran` example:
```
./openapisaurus split \
ref/fivetran/swagger.json \
--providerName=fivetran \
--svcdiscriminator='["tags"][0]' \
--outputDir=dev \
--overwrite \
--verbose
```
`digitalocean` example:
```
./openapisaurus split \
ref/digitalocean/digitalocean-openapi-bundled.yaml \
--providerName=digitalocean \
--svcdiscriminator='["tags"][0]' \
--outputDir=dev \
--overwrite
```
### `dev`
Generate stackql provider development provider docs.
> __Usage:__
> `openapisaurus dev `
>
> __Arguments:__
> `apiDocDir` __[REQUIRED]__ Directory containing OpenAPI specifications used to create StackQL dev docs.
>
> __Flags:__
> `--providerName` __[REQUIRED]__ Name of the provider.
> `--resDiscriminator` __[REQUIRED]__ [JMESPath](https://jmespath.org/) used to identify stackql resources from an OpenAPI spec.
> (defaults to `path_tokens`).
> `--providerConfig` __[OPTIONAL]__ Stringified JSON object, describing the config for a provider.
> (defaults to `{ "auth": { "type": "null_auth" }}`).
> `--methodKey` __[OPTIONAL]__ [JMESPath](https://jmespath.org/) used to identify resource methods from a providers OpenAPI spec.
> (defaults to `operationId`).
> `--overwrite` __[OPTIONAL]__ Overwrite existing files. (defaults to `false`)
> `--verbose` __[OPTIONAL]__ Verbose output (defaults to `false`).
#### Examples
`fivetran` example:
```
./openapisaurus dev \
dev \
--providerName=fivetran \
--providerConfig='{ "auth": { "type": "basic", "credentialsenvvar": "FIVETRAN_CREDS" }}' \
--overwrite \
--verbose
```
`digitalocean` example:
```
./openapisaurus dev \
dev \
--providerName=digitalocean \
--providerConfig='{ "auth": { "type": "bearer", "credentialsenvvar": "DIGITALOCEAN_TOKEN" }}' \
--overwrite \
--verbose
```
### `build`
Build deployable stackql provider docs.
> __Usage:__
> `openapisaurus build `
>
> __Arguments:__
> `apiDocDir` __[REQUIRED]__ Directory containing OpenAPI service specifications and StackQL dev docs.
>
> __Flags:__
> `--providerName` __[REQUIRED]__ Name of the provider.
> `--outputDir` __[REQUIRED]__ Output directory to write compiled docs to.
> `--servers` __[OPTIONAL]__ Stringified JSON array containing servers for the provider.
> (overrides the `servers` list in the original OpenAPI spec).
> `--overwrite` __[OPTIONAL]__ Overwrite existing files. (defaults to `false`)
> `--verbose` __[OPTIONAL]__ Verbose output (defaults to `false`).
#### Examples
`fivetran` example:
```
./openapisaurus build \
dev \
--providerName=fivetran \
--outputDir=src \
--overwrite \
--verbose
```
`digitalocean` example:
```
./openapisaurus build \
dev \
--providerName=digitalocean \
--outputDir=src \
--overwrite \
--verbose
```
## Run provider meta tests
> to run tests locally you will need to download `stackql`, to download the latest `stackql` release for Linux you can use the following commands:
> `curl -L https://bit.ly/stackql-zip -O && unzip stackql-zip`
## Testing providers using the local registry
To test providers using the local registry, you can use the following commands:
```
PROVIDER_REGISTRY_ROOT_DIR="$(pwd)"
REG_STR='{"url": "file://'${PROVIDER_REGISTRY_ROOT_DIR}'", "localDocRoot": "'${PROVIDER_REGISTRY_ROOT_DIR}'", "verifyConfig": {"nopVerify": true}}'
./stackql shell --registry="${REG_STR}"
```
## Running without `openapisaurus`
To run directly without using the `openapisaurus` script, you can use the following command as an example:
```
deno run \
--allow-net \
--allow-read \
--allow-write \
app.ts split \
../../local-registry/ref/fivetran/swagger.json \
--providerName=fivetran \
--svcdiscriminator='["tags"][0]' \
--overwrite \
--verbose
```
If you have any issues with `openapisaurus`, please report them [here](https://github.com/stackql/openapisaurus/issues).
## License
This project is licensed under the [MIT License](LICENSE).