{"id":21262857,"url":"https://github.com/stackql/openapisaurus","last_synced_at":"2025-07-11T04:31:19.506Z","repository":{"id":163903790,"uuid":"610975224","full_name":"stackql/openapisaurus","owner":"stackql","description":"Deno based openapi document utility for splitting openapi spec and generating stackql providers","archived":false,"fork":false,"pushed_at":"2024-10-30T01:28:37.000Z","size":7533,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-30T08:58:16.740Z","etag":null,"topics":["openapi","rest","sql","stackql"],"latest_commit_sha":null,"homepage":"https://stackql.io/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stackql.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-07T21:20:38.000Z","updated_at":"2024-10-30T01:00:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"5c13ff61-8d08-4856-8b71-b4ff54be0ea3","html_url":"https://github.com/stackql/openapisaurus","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fopenapisaurus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fopenapisaurus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fopenapisaurus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fopenapisaurus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackql","download_url":"https://codeload.github.com/stackql/openapisaurus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225674897,"owners_count":17506272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openapi","rest","sql","stackql"],"created_at":"2024-11-21T04:59:32.786Z","updated_at":"2024-11-21T04:59:33.264Z","avatar_url":"https://github.com/stackql.png","language":"TypeScript","readme":"# openapisaurus\n\n\u003e Command line utility to split OpenAPI documents into smaller, self contained, service oriented documents and prepare StackQL provider interfaces\n\u003e Command line utility to help developers prepare and submit StackQL provider specs, see [StackQL](https://github.com/stackql/stackql)\n\n`openapisaurus` is implemented in TypeScript and designed to be run using the [`deno`](https://deno.land/) runtime.\n\n## Installation\n\n1. Install Deno by following the instructions at [deno.land](https://deno.land/).\n2. Clone the `openapisaurus` repository to your local machine:\n```\ngit clone git@github.com:stackql/openapisaurus.git\n```\n3. Make the `openapisaurus` script executable by running the following command:\n```\nchmod +x openapisaurus\n```\n\n## Command Line Usage\n\n### `split`\n\nSplits an OpenAPI spec into multiple service scoped documents.  \n\n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Usage:__   \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`openapisaurus split \u003capiDoc\u003e \u003cflags\u003e`  \n\u003e \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Arguments:__  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`apiDoc`  __[REQUIRED]__ OpenAPI specification to be split.  \n\u003e \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Flags:__  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--providerName`      __[REQUIRED]__ Name of the provider.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--svcDiscriminator`  __[REQUIRED]__ [JMESPath](https://jmespath.org/) expression to extract the service name from the OpenAPI spec.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--exclude`           __[OPTIONAL]__ [JMESPath](https://jmespath.org/) expression for paths to exclude from processing.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--outputDir`         __[OPTIONAL]__ Directory to write the output OpenAPI documents to. (defaults to `cwd`)  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--overwrite`         __[OPTIONAL]__ Overwrite existing files. (defaults to `false`)  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--verbose`           __[OPTIONAL]__ Verbose output (defaults to `false`).  \n\n#### Examples\n\n`fivetran` example:  \n\n```\n./openapisaurus split \\\nref/fivetran/swagger.json \\\n--providerName=fivetran \\\n--svcdiscriminator='[\"tags\"][0]' \\\n--outputDir=dev \\\n--overwrite \\\n--verbose\n```\n\n`digitalocean` example:  \n\n```\n./openapisaurus split \\\nref/digitalocean/digitalocean-openapi-bundled.yaml \\\n--providerName=digitalocean \\\n--svcdiscriminator='[\"tags\"][0]' \\\n--outputDir=dev \\\n--overwrite\n```\n\n### `dev`\n\nGenerate stackql provider development provider docs.    \n\n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Usage:__   \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`openapisaurus dev \u003capiDocDir\u003e \u003cflags\u003e`  \n\u003e \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Arguments:__  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`apiDocDir`  __[REQUIRED]__ Directory containing OpenAPI specifications used to create StackQL dev docs.  \n\u003e \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Flags:__  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--providerName`      __[REQUIRED]__ Name of the provider.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--resDiscriminator`  __[REQUIRED]__ [JMESPath](https://jmespath.org/) used to identify stackql resources from an OpenAPI spec.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; (defaults to `path_tokens`).  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--providerConfig`    __[OPTIONAL]__ Stringified JSON object, describing the config for a provider.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; (defaults to `{ \"auth\": { \"type\": \"null_auth\" }}`).  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--methodKey`         __[OPTIONAL]__ [JMESPath](https://jmespath.org/) used to identify resource methods from a providers OpenAPI spec.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; (defaults to `operationId`).  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--overwrite`         __[OPTIONAL]__ Overwrite existing files. (defaults to `false`)  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--verbose`           __[OPTIONAL]__ Verbose output (defaults to `false`).  \n\n#### Examples\n\n`fivetran` example:  \n\n```\n./openapisaurus dev \\\ndev \\\n--providerName=fivetran \\\n--providerConfig='{ \"auth\": { \"type\": \"basic\", \"credentialsenvvar\": \"FIVETRAN_CREDS\" }}' \\\n--overwrite \\\n--verbose\n```\n\n`digitalocean` example:  \n\n```\n./openapisaurus dev \\\ndev \\\n--providerName=digitalocean \\\n--providerConfig='{ \"auth\": { \"type\": \"bearer\", \"credentialsenvvar\": \"DIGITALOCEAN_TOKEN\" }}' \\\n--overwrite \\\n--verbose\n```\n\n### `build`\n\nBuild deployable stackql provider docs.   \n\n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Usage:__   \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`openapisaurus build \u003capiDocDir\u003e \u003cflags\u003e`  \n\u003e \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Arguments:__  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`apiDocDir`  __[REQUIRED]__ Directory containing OpenAPI service specifications and StackQL dev docs.  \n\u003e \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;__Flags:__  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--providerName`      __[REQUIRED]__ Name of the provider.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--outputDir`         __[REQUIRED]__ Output directory to write compiled docs to.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--servers`    __[OPTIONAL]__ Stringified JSON array containing servers for the provider.  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; (overrides the `servers` list in the original OpenAPI spec).  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--overwrite`         __[OPTIONAL]__ Overwrite existing files. (defaults to `false`)  \n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;`--verbose`           __[OPTIONAL]__ Verbose output (defaults to `false`).  \n\n#### Examples\n\n`fivetran` example:  \n\n```\n./openapisaurus build \\\ndev \\\n--providerName=fivetran \\\n--outputDir=src \\\n--overwrite \\\n--verbose\n```\n\n`digitalocean` example:  \n\n```\n./openapisaurus build \\\ndev \\\n--providerName=digitalocean \\\n--outputDir=src \\\n--overwrite \\\n--verbose\n```\n\n## Run provider meta tests\n\n\u003e to run tests locally you will need to download `stackql`, to download the latest `stackql` release for Linux you can use the following commands:  \n\u003e `curl -L https://bit.ly/stackql-zip -O \u0026\u0026 unzip stackql-zip`\n\n## Testing providers using the local registry\n\nTo test providers using the local registry, you can use the following commands:  \n\n```\nPROVIDER_REGISTRY_ROOT_DIR=\"$(pwd)\"\nREG_STR='{\"url\": \"file://'${PROVIDER_REGISTRY_ROOT_DIR}'\", \"localDocRoot\": \"'${PROVIDER_REGISTRY_ROOT_DIR}'\", \"verifyConfig\": {\"nopVerify\": true}}'\n./stackql shell --registry=\"${REG_STR}\"\n```\n## Running without `openapisaurus`\n\nTo run directly without using the `openapisaurus` script, you can use the following command as an example:  \n\n```\ndeno run \\\n--allow-net \\\n--allow-read \\\n--allow-write \\\napp.ts split \\\n../../local-registry/ref/fivetran/swagger.json \\\n--providerName=fivetran \\\n--svcdiscriminator='[\"tags\"][0]' \\\n--overwrite \\\n--verbose \n```\n\nIf you have any issues with `openapisaurus`, please report them [here](https://github.com/stackql/openapisaurus/issues).\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fopenapisaurus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackql%2Fopenapisaurus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fopenapisaurus/lists"}