{"id":21262868,"url":"https://github.com/stackql/stackql-azure-openapi","last_synced_at":"2025-08-08T13:19:39.756Z","repository":{"id":59884184,"uuid":"522469749","full_name":"stackql/stackql-azure-openapi","owner":"stackql","description":"Generates a single OpenAPI document for each Azure Resource Manager service from a set of OpenAPI specifications sourced from Azure REST API specs","archived":false,"fork":false,"pushed_at":"2024-10-18T00:38:07.000Z","size":30443,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-21T06:16:03.810Z","etag":null,"topics":["autorest","azure","azurerm","javascript","nodejs","openapi","openapi3","stackql","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"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":null,"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":"2022-08-08T08:41:58.000Z","updated_at":"2024-10-18T00:38:13.000Z","dependencies_parsed_at":"2024-10-20T01:39:52.230Z","dependency_job_id":null,"html_url":"https://github.com/stackql/stackql-azure-openapi","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%2Fstackql-azure-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-azure-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-azure-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-azure-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackql","download_url":"https://codeload.github.com/stackql/stackql-azure-openapi/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":["autorest","azure","azurerm","javascript","nodejs","openapi","openapi3","stackql","typescript"],"created_at":"2024-11-21T04:59:34.317Z","updated_at":"2024-11-21T04:59:35.062Z","avatar_url":"https://github.com/stackql.png","language":"JavaScript","readme":"# Azure OpenAPI Doc Generator\n\nGenerates a single OpenAPI document for each Azure Resource Manager service from a set of OpenAPI specifications sourced from [__azure-rest-api-specs__](https://github.com/Azure/azure-rest-api-specs).  \n\nThis project uses [__autorest__](https://github.com/Azure/autorest) via JavaScript to emit the latest set of OpenAPI specifications for each service,  then dereferences and combines the documents into a single YAML OpenAPI specification using [__APIDevTools/json-schema-ref-parser__](https://github.com/APIDevTools/json-schema-ref-parser). \n\n\u003e a complete set of specs for each service is available [here](https://github.com/stackql/stackql-azure-openapi/tree/main/openapi/3-combined)\n\n\u003e a set of specs for each service used to generate the `azure` and `azure_extras` `stackql` provider is available [here](https://github.com/stackql/stackql-azure-openapi/tree/main/openapi/4-tagged)  \n\n## Usage\n\n\u003e use the `prereq.sh` script or the equivalent to download the latest api documentation from [__azure-rest-api-specs__](https://github.com/Azure/azure-rest-api-specs)\n\n\u003e use `run.sh` script or the equivalent to run all the `stackql-azure-openapi` commands in a batch\n\nThe main entrypoint to the program is:  \n\n```bash\nbin/stackql-azure-openapi\n```\n\nThis can be run without any arguments to get command line usage and help.  The `stackql-azure-openapi` commands include:\n\n- `generate` : uses `autorest` to generate initial OpenAPI3 specs for one or many services\n- `dereference` : dereferences all external JSON pointers in the generated OpenAPI specs\n- `combine` : combines all the generated OpenAPI specs into a single OpenAPI spec\n- `tag` : replaces existing tags for operations with the stackql resource name (optional)\n\nThese commands are intended to be run in sequence with the output of each command being the input to the next.  The flow is summarized below:  \n\n### IMAGE\n\n[![stackql_azure_openapi](images/stackql_azure_openapi.png)](images/stackql_azure_openapi.png)\n\nSpecific details about each command are provided in the sections below.  \n\n## `generate` command\n\nUses `autorest` to generate initial OpenAPI3 specs for one or many services using the `autorest` configuration data in the `readme.md` in each service specification directory from the `main` branch of the [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) repo.  Conceptually this would be similar to running the following command in each subdirectory of the `specification` folder:      \n\n```bash\nautorest ./resource-manager/readme.md \\\n--openapi-type=arm \\\n--output-converted-oai3\n```\n\nThe output of this command is a directory structure (n-levels deep) containing OpenAPI JSON documents with references to each other (using JSON `$refs`), the union of which forms a complete specification for the service.  \n\nTo generate specs for a single service (the `compute` service in this example), run the following command:\n\n```bash\nbin/stackql-azure-openapi generate compute\n```\n\nTo generate specs for all services, run the following command:\n\n```bash\nbin/stackql-azure-openapi generate\n```\n\n## `dereference` command\n\nTakes the output from the `generated` command, enumerates all JSON documents nested at any level in the directory structure, and dereferences all JSON pointers in each document, outputting a flat structure containing a document for each generated document found for each service with no external references.  \n\nTo dereference a set of `autorest` generated specs for a single service (the `compute` service in this example), run the following command:\n\n```bash\nbin/stackql-azure-openapi dereference compute\n```\n\nTo dereference specs for all services, run the following command:\n\n```bash\nbin/stackql-azure-openapi dereference\n```\n\n## `combine` command\n\nTakes the output from the `dereference` command, and combines all the generated documents into a single OpenAPI spec, outputting a single, self contained YAML document (removing the `examples` for brevity).  \n\nTo create a single OpenAPI document for a single service (the `compute` service in this example), run the following command:\n\n```bash\nbin/stackql-azure-openapi combine compute\n```\n\nTo create a single OpenAPI document for all services, run the following command:\n\n```bash\nbin/stackql-azure-openapi combine\n```\n\n## `tag` command (Optional)\n\nTakes the output from the `combine` command, generates the stackql resource name from stemming the `operationId` for each operation, pushes this value to the beginning of the `tags` array for each operation, and outputs the resulting document.    \n\nTo update tags for a single OpenAPI document for a single service (the `compute` service in this example), run the following command:  \n\n```bash\nbin/stackql-azure-openapi tag compute\n```\n\nTo tags fo all OpenAPI documents for all services, run the following command:\n\n```bash\nbin/stackql-azure-openapi tag\n```\n\n## Testing locally with `stackql`\n1. download the latest `stackql` binary, for example `curl -L https://bit.ly/stackql-zip -O \u0026\u0026 unzip stackql-zip` for Linux systems\n2. run the following:\n```\nPROVIDER_REGISTRY_ROOT_DIR=\"$(pwd)/openapi\"\nREG_STR='{\"url\": \"file://'${PROVIDER_REGISTRY_ROOT_DIR}'\", \"localDocRoot\": \"'${PROVIDER_REGISTRY_ROOT_DIR}'\", \"verifyConfig\": {\"nopVerify\": true}}'\n./stackql shell --registry=\"${REG_STR}\"\n```\n\n### Run Test Suite\n\nfrom the `stackql-provider-tests` directory:\n\n```bash\ncd ../../stackql-provider-tests\n\n# azure\nsh test-provider.sh \\\nazure \\\nfalse \\\n/mnt/c/LocalGitRepos/stackql/openapi-conversion/stackql-azure-openapi/openapi \\\ntrue\n\n# azure_extras\nsh test-provider.sh \\\nazure_extras \\\nfalse \\\n/mnt/c/LocalGitRepos/stackql/openapi-conversion/stackql-azure-openapi/openapi \\\ntrue\n\n# azure_isv\nsh test-provider.sh \\\nazure_isv \\\nfalse \\\n/mnt/c/LocalGitRepos/stackql/openapi-conversion/stackql-azure-openapi/openapi \\\ntrue\n\n# azure_stack\nsh test-provider.sh \\\nazure_stack \\\nfalse \\\n/mnt/c/LocalGitRepos/stackql/openapi-conversion/stackql-azure-openapi/openapi \\\ntrue\n```\n\n# Document\n\n```bash\nsh start-stackql-server.sh\nbin/stackql-azure-openapi doc azure\nbin/stackql-azure-openapi doc azure_isv\nbin/stackql-azure-openapi doc azure_stack\nbin/stackql-azure-openapi doc azure_extras\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-azure-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackql%2Fstackql-azure-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-azure-openapi/lists"}