publish-postman: wrap tags under APIs folder, alphabetize, fix V2 example option

[Devon-White]

Summary

Three independent improvements to the OpenAPI → Postman conversion pipeline. Each is isolated to either the workflow jq pass or the converter options file — no spec changes, no behavioral risk to anything outside Postman publishing.

1. Wrap tag folders under a top-level APIs folder

Top-level collection layout becomes:

collection.item[]
├── APIs
│   ├── (every tag-derived folder, alphabetized)
│   └── …
└── Webhooks
    └── (unchanged)

The Webhooks folder is hardcoded by openapi-to-postmanv2 (libV2/.../generateFolderForOpenAPI.js:6) — every webhook lands there regardless of how it's tagged in the spec, because _generateWebhookEndpoints runs separately from _generateTreeFromTags and doesn't consult folderStrategy. Partitioning by the literal name "Webhooks" is therefore stable.

2. Alphabetize APIs folder, case-insensitively

sort_by(.name | ascii_downcase) puts cXML * near Call Flows (instead of dropping to the bottom of the list under ASCII byte order where lowercase c > uppercase W), and SWML * after Subscribers per dictionary convention.

Per-tag request order is not sorted (left to the converter's path/method order). The Webhooks folder contents are also unchanged.

3. Fix parametersResolution option name (V1 → V2)

openapi-to-postmanv2@6.0.1 defaults to the V2 module (bin/openapi2postmanv2.js:136), which only reads the unified parametersResolution option. The previous config passed V1-only names (requestParametersResolution, exampleParametersResolution) through -c <file> — and the CLI's V1→V2 backfill (lines 54-56) only runs for -O key=value args, not for config files. So V2 silently fell back to its default Schema faker, ignoring the spec's @example decorators.

Result: operation-level requestBody.content.<mime>.examples blocks now populate the Postman request body correctly, instead of returning faker placeholders like <string>.

Verification

Tested against both watched specs locally with openapi-to-postmanv2@6.0.1:

Spec	Before	After
signalwire-rest	60 flat top-level folders, semi-random order, faker-generated example values	APIs (59 children, alphabetized) + Webhooks (4 children); real example values for operations with named examples: blocks
compatibility	22 flat top-level folders	APIs (21 children) + Webhooks (5 children)

Postman SDK (postman-collection@4) parses both payloads cleanly — no schema regressions.

Out of scope

• Spec-level @example decorators still don't surface for nested properties — the bundled 2018-era json-schema-faker only reads singular example:, not the plural examples: array form that OpenAPI 3.1 / TypeSpec emits. Separate problem with no clean fix in the current converter; documented in the team Slack thread.
• oneOf request body variants still render only the first variant — this is hardcoded in libV2/.../schemaUtils.js:612 (compositeSchema[0]) with no option to control it. PR #768's matched-key multi-example support was deliberately reverted upstream in v5.8.0 by PR #925. Separate decision pending.

Files

• .github/workflows/publish-postman.yml — extended jq pipeline (partition + sort + wrap) in the existing 'strip IDs and wrap for PUT' step. Conversion step, link-rewrite step, and PUT step untouched.
• scripts/postman/convert-options.json — replaced two V1-only options with the unified V2 option.

How to verify after merge

The next push to main that changes either fern/apis/signalwire-rest/openapi.yaml or fern/apis/compatibility/openapi.yaml will publish the new layout. Or trigger workflow_dispatch with force_all: true to republish immediately.

[github-actions]

🌿 Preview

https://signalwire-preview-2e87b1d6-e75e-4d6f-a351-abc69963f186.docs.buildwithfern.com/docs

---

View workflow run