postman-cs/Postman Onboarding: Azure Spec Discovery
Discover Azure-hosted API specs and expose a spec path for Postman onboarding. Part of the Postman API Onboarding suite.
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Stale
- License
- None
Inputs
| name | description | required | default |
|---|---|---|---|
| mode | Discovery mode: resolve-one selects the single best service for this repository; discover-many exports every exportable candidate; discover-estate enumerates repo-associated Azure resources across the selected subscription scope(s) without exporting specs. | no | resolve-one |
| subscription-id | Optional Azure subscription ID used as the discovery enumeration root. When omitted, the single enabled subscription visible to the credential is used; multiple enabled subscriptions require this input or subscription-ids-json. | no | "" |
| subscription-ids-json | Optional JSON array of Azure subscription IDs for explicit multi-subscription discovery. Conflicts with subscription-id unless both identify exactly the same one ID. Empty keeps single-enabled-subscription behavior. Never auto-enumerates all visible subscriptions. | no | "" |
| resource-group | Optional resource group that scopes discovery to one group instead of the whole subscription. | no | "" |
| api-id | Optional full APIM API ARM resource ID for this service. Use this to bypass broader subscription discovery. Supports historical revisions via ;rev=N. | no | "" |
| environment | Optional deployment environment selector used to disambiguate APIs that share a repository association across environments. | no | "" |
| gateway-id | Optional self-hosted or workspace gateway id used to narrow APIM API candidates. The value "managed" is rejected. | no | "" |
| api-version | Optional APIM API version selector used when multiple versions share the same path or repository association. | no | "" |
| api-revision | Optional APIM API revision selector used when multiple revisions remain after other evidence. | no | "" |
| api-center-definition-id | Optional full Azure API Center definition ARM resource ID. Exact match only; conflicts with a different .postman apiCenterDefinitionId binding. | no | "" |
| output-dir | Directory under the repository root where generated specs are written. | no | discovered-specs |
| postman-api-key | Optional service-account PMAK used to mint or re-mint a postman-access-token for telemetry enrichment (account_type). Not used for any Azure or Postman asset operation. | no | "" |
| postman-access-token | Optional Postman service-account access token, used only to enrich anonymous telemetry with the session account_type. When omitted, postman-api-key alone can mint one for the same purpose. Not used for any Azure or Postman asset operation. | no | "" |
| enable-logic-apps-list-swagger | Opt-in Consumption Logic Apps native listSwagger POST. Default false. When denied or capability-absent, falls back to Reader-only Request-trigger synthesis unless require-logic-apps-native-swagger is true. | no | false |
| require-logic-apps-native-swagger | When true with enable-logic-apps-list-swagger, a permanent malformed native listSwagger response fails instead of silently synthesizing. Default false. | no | false |
| enable-app-service-scm-spec-fetch | Opt-in retrieval of App Service aiIntegration.ApiSpecPath bytes through the site SCM/VFS endpoint. Default false. Metadata is still surfaced when the path is present. | no | false |
| enable-functions-openapi-extension | Opt-in detection/export of Azure Functions OpenAPI extension endpoints evidenced by function metadata or an explicit declared path. Default false. Never lists host/function keys. | no | false |
| enable-runtime-declared-spec-routes | Opt-in provider for explicitly declared HTTPS specification URLs on App Service, Functions, Container Apps, Static Web Apps, ACI, and AKS workloads. Default false. No blind common-path probing. | no | false |
| runtime-declared-spec-targets-json | Requested subset of runtime-declared HTTPS specification targets when enable-runtime-declared-spec-routes is true. Each entry requires id, name, workloadKind, and https url. Caller JSON alone is rejected; every target must match a committed .postman/repository binding or authorized ARM association evidence. | no | [] |
Outputs
| name | description |
|---|---|
| resolution-json | JSON resolution result describing status, source type, confidence, and evidence. |
| resolution-status | Resolution status: resolved or unresolved. |
| source-type | Resolved source type: repo-spec, apim-export, api-center-export, app-service-api-definition, iac-embedded, custom-api-swagger, logic-apps-workflow, template-spec-embedded, event-grid-webhook, service-bus-topic, function-bindings-trigger, runtime-declared-spec, manual-review, discover-many, or discover-estate. |
| mapping-confidence | Numeric confidence score for the selected service candidate. |
| spec-path | Path to the resolved or generated specification when available. |
| spec-files-json | Optional JSON inventory of an authoritative multi-file definition set (schemaVersion 1: root, format, completeness, provenance, sorted files with path/role/bytes/sha256). Empty for single-file, unresolved, or incomplete/partial source sets. Never embeds file content. |
| api-id | Full APIM API ARM resource ID or API Center definition ARM resource ID when those providers resolve; empty for App Service or IaC-local resolutions. |
| service-name | Resolved service name. |
| services-json | discover-many output: JSON array of exported services. |
| service-count | discover-many output: number of exported services. |
| export-summary-json | JSON summary of attempted, exported, failed, and skipped candidates. |
| candidates-json | Ranked ambiguous candidates as JSON when resolution is unresolved with at least two candidates; empty otherwise. |
| provider-type | Provider that produced the resolved spec: apim, api-center, app-service, iac-local, custom-apis, logic-apps, template-specs, event-grid, service-bus, function-bindings, or runtime-declared. |
| spec-format | Format of the resolved spec: openapi-yaml, openapi-json, asyncapi-yaml, asyncapi-json, wsdl, wadl, xsd, protobuf, graphql-sdl, or mcp-json. |
| contract-origin | Compatibility output; always empty in v1. |
| contract-metadata-path | Compatibility output; always empty in v1. |
| variant-count | Compatibility output; always empty in v1. |
| derived-openapi-path | Path to the derived OpenAPI 3.x document when the source was not already OpenAPI 3.x. |
| derived-openapi-version | OpenAPI version of the derived document: 3.0.3 or 3.1.0. |
| derived-openapi-completeness | Whether the derived OpenAPI document is full or partial. |
| derived-openapi-format | Serialization format of the derived OpenAPI document: openapi-json. |
| derived-openapi-evidence-json | JSON array of evidence strings describing how the derived OpenAPI document was produced. |
| narrowing-strategy | Narrowing tier that produced the candidate ordering: gateway-host-path, tag-prefilter, gateway-assignment, iac-fingerprint, rg-correlation, naming-heuristic, or none. |
| repos-json | discover-estate output: JSON array of deduped org/repo associations discovered from repo tags across the selected subscription scope(s); empty otherwise. |
| repo-count | discover-estate output: number of deduped org/repo associations; empty otherwise. |