Repository files navigation

Command line utility to split OpenAPI documents into smaller, self contained, service oriented documents and prepare StackQL provider interfacesCommand line utility to help developers prepare and submit StackQL provider specs, seeStackQL Readme

npm i @stackql/openapi-doc-util

yarn add @stackql/openapi-doc-util

from the package directory, run:

npm link

provider/├─ service/│  ├─ resource/│  │  ├─ fields│  │  ├─ methods

google/├─ compute/│  ├─ instances/│  │  ├─ id, name, status, ...│  │  ├─ select, insert, delete, start, stop, ...

SHOW RESOURCESINgoogle.compute;DESCRIBEgoogle.compute.instances;

SELECT status,COUNT(*)as num_instancesFROMgoogle.compute.instancesWHERE project='myproject'and zone='us-west-1a'GROUP BY status;

openapi-doc-util<command> [<arguments(s)>] [<flag(s)>]

validate

Validates an OpenAPI specification document.

split

Splits an Open API document into smaller, self contained, service scoped documents based upon a specified service discriminator (JSONPath expression relative to each operation). Takes an OpenAPI document as input and outputs the following structure:

{output_dir}/├─ {provider_name}/│  ├─ {provider_version}/│  │  ├─ services/│  │  │  ├─ {service_name}/│  │  │  │  ├─ {service_name}.yaml│  │  │  ├─ .../

The{service_name}.yaml file is a self contained, OpenAPI specification document, containing only operations and components for the specified service.

provider-dev

Iterates through a directory of services (created using thesplit function), generates an additional document for each service{service_name}-resources.yaml and an index document for all services namedprovider.yaml, this is useful for developing new StackQL providers. The output structure is as follows:

{api_doc_dir}/├─ {provider_name}/│  ├─ {provider_version}/│  │  ├─ services/│  │  │  ├─ {service_name}/│  │  │  │  ├─ {service_name}.yaml│  │  │  │  ├─ {service_name}-resources.yaml│  │  │  ├─ .../│  │  ├─ provider.yaml

The original OpenAPI documents are not modified.

Theprovider-dev function will infer SQL routes for operations under each resources under thesqlVerbs key, this should be reviewed by the developer, removing any duplicate or erroneous routes.

provider-build

Operates on the dev directory structure generated using theprovider-dev command, assembles a complete Open API specification per service including the StackQL resources for each service in each document undercomponents/x-stackQL-resources, and outputs the following structure to a new directory:

{output_dir}/├─ {provider_name}/│  ├─ {provider_version}/│  │  ├─ services/│  │  │  ├─ {service_name}/│  │  │  │  ├─ {service_name}.yaml│  │  │  ├─ .../│  │  ├─ provider.yaml

The output from theprovider-build command can be used to test locally (seeTest Using a Local Registry). Once you have tested locally you can raise a pull request tostackql/stackql-provider-registry.

--svcDiscriminator,-sJSONPath expression ORsvcName:servicename

Theservice discriminator option is used to determine how to split a large provider document into smaller, service scoped documents. The option is required for thesplit command and ignored otherwise. If you do not wish to spilt the provider API spec, specifysvcName:<servicename> for this option which will define one service in the StackQL provider with the name provided inservicename.

Example:-s "$['x-github'].category" would split the given provider API spec into service documents by matching thex-github.category value in each unique operation (combination of a path and an HTTP method) in API doc.

--resDiscriminator,-rJSONPath expression ORpath_tokens

Theresource discriminator option is used to determine how to identify StackQL resources in a given provider API spec. This option is used for theprovider-dev command and ignored otherwise.

Example:-r "$['x-github'].subcategory" would identify resources in the given provider API spec by matching thex-github.subcategory value in each unique operation (combination of a path and an HTTP method) in API doc.

ifpath_tokens is specified for the--resDiscriminator option, the resource name will be derived by joining the 'meaningful' path tokens (not equivalent to the service name) with an '_'. For instance a path of/sites/{site_id}/service-instances would result in a resource name ofsites_service_instances assuming the service name was notsites.

--methodkey,-mJSONPath expression

Themethod key option determines uniquely named operations which are mapped to SQL methods in the StackQL ORM. These methods are then mapped to default routes (SQL query and DML methods) in StackQL, the developer can override or update these mappings in the development docs which are outputted from theprovider-dev command. This option is used for theprovider-dev command and ignored otherwise.

If supplied it must be a JSONPath expression relative to the operation (http path and verb), if not supplied it will default tooperationId in the OpenAPI specification for each operation.

--output,-odirectory

Theoutput directory option specifies the root directory to output files from thesplit, or the root directory to output assembled provider specs from theprovider-build command. The default is the current working directory. If the directory exists in either case the program will exit with an error unless the--overwrite option is set.

If not supplied it will default to the current working directory

--overwrite

Theoverwrite option specifies whether to overwrite files in the output directory. The default isfalse.

--debug,-d

debug flag which can be set for additional print statements.

This example demonstrates creating a StackQL provider forgithub and testing this provider locally usingstackql

The following directory structure represents the target after an API dev workspace is set up and the StackQL provider forgithub is built.

local-registry/├─ ref/│  ├─ github/│  │  ├─ api.github.com.yaml├─ dev/│  ├─ github/│  │  ├─ v0.1.0/│  │  │  ├─ provider.yaml│  │  │  ├─ services/│  │  │  │  ├─ repos/│  │  │  │  │  ├─ repos.yaml│  │  │  │  │  ├─ repos-resources.yaml│  │  │  │  ├─ .../├─ src/│  ├─ github/│  │  ├─ v0.1.0/│  │  │  ├─ provider.json│  │  │  ├─ services/│  │  │  │  ├─ repos/│  │  │  │  │  ├─ repos-v0.1.0.json

local-registry/ref/github/api.github.com.yaml is the source OpenAPI 3 specification for thegithub api, this was sourced fromGitHub.

Thedev directory contains the output of the dev docs generated by theopenapi-doc-util split command, which will then serve as input to theopenapi-doc-util provider-dev command.

Thesrc directory contains the output of the StackQL provider interface generated from the dev docs usingopenapi-doc-util provider-build.

PowerShell:

cd local-registryopenapi-doc-util split`-n github`-v v0.1.0`-s"$['x-github'].category"`-o .\dev`./ref/github/api.github.com.yaml

Bash:

cd local-registryopenapi-doc-util split \-n github \-v v0.1.0 \-s'$["x-github"].category' \-o ./dev \ref/github/api.github.com.yaml

PowerShell:

cd local-registryopenapi-doc-util provider-dev`-n github`-v v0.1.0`-r"$['x-github'].subcategory"`.\dev

Bash:

cd local-registryopenapi-doc-util provider-dev \-n github \-v v0.1.0 \-r'$["x-github"].subcategory' \./dev

PowerShell:

cd local-registryopenapi-doc-util provider-build`-n github`-v v0.1.0`-o .\src`.\dev

Bash:

cd local-registryopenapi-doc-util provider-build \-n github \-v v0.1.0 \-o ./src \./dev

cd local-registryPROVIDER_REGISTRY_ROOT_DIR="$(pwd)"REG_STR='{"url": "file://'${PROVIDER_REGISTRY_ROOT_DIR}'", "localDocRoot": "'${PROVIDER_REGISTRY_ROOT_DIR}'", "verifyConfig": {"nopVerify": true}}'AUTH_STR='{"github": { "type": "null_auth" }}'./stackql shell --auth="${AUTH_STR}" --registry="${REG_STR}"