stackql/openapisaurus

Deno based openapi document utility for splitting openapi spec and generating stackql providers

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

openapisaurus is implemented in TypeScript and designed to be run using the deno runtime.

Installation

1. Install Deno by following the instructions at deno.land.
2. Clone the openapisaurus repository to your local machine:

git clone git@github.com: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 <apiDoc> <flags>

   Arguments:
      apiDoc [REQUIRED] OpenAPI specification to be split.

   Flags:
      --providerName [REQUIRED] Name of the provider.
      --svcDiscriminator [REQUIRED] JMESPath expression to extract the service name from the OpenAPI spec.
      --exclude [OPTIONAL] JMESPath 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 <apiDocDir> <flags>

   Arguments:
      apiDocDir [REQUIRED] Directory containing OpenAPI specifications used to create StackQL dev docs.

   Flags:
      --providerName [REQUIRED] Name of the provider.
      --resDiscriminator [REQUIRED] JMESPath 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 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 <apiDocDir> <flags>

   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.

License

This project is licensed under the MIT License.