Add apim-gen CLI for automated Azure APIM-compatible OpenAPI spec generation

[brunoamui]

Summary

• Adds apim-gen CLI tool that transforms VTEX OpenAPI specs into Azure APIM-compatible versions
• Configurable per-client via YAML config with composable transform pipeline
• Includes GitHub Actions workflow that auto-generates and commits specs on PRs

Problem

Importing VTEX OpenAPI specs into Azure API Management requires manual patching to work around APIM's strict parser. A colleague manually patched 25+ specs for the Manitou project — this tool automates that process.

Azure APIM Compatibility Issues Solved

#	Issue	Transform
1	False path parameters — {accountName} and {environment} in paths are server variables, not path params. APIM rejects these.	remove-false-path-params
2	Header params that APIM rejects — Accept and Content-Type as explicit parameters conflict with APIM's handling.	remove-params
3	Duplicate/ambiguous paths — MasterData v1 has overlapping CL/AD entity paths.	remove-paths
4	Missing operationId — APIM requires operationId on every operation.	ensure-operation-id
5	OpenAPI version — Some specs use 3.0.x versions APIM doesn't handle well.	set-openapi-version
6	Large specs need splitting — Catalog and Orders APIs are too large for single APIM import.	split-by-prefix
7	Unused components — After splitting, orphaned schemas/params remain.	cleanup-components

Architecture

clients/{name}/config.yaml  →  apim-gen CLI  →  clients/{name}/output/*.json
                                    ↑
                            tools/apim-gen/src/
                            ├── types.ts          (type definitions)
                            ├── config.ts         (YAML config loader)
                            ├── pipeline.ts       (orchestration)
                            ├── cli.ts            (entry point)
                            └── transforms/       (8 composable transforms)

Usage

# Generate specs for a specific client
npx tsx tools/apim-gen/src/cli.ts generate clients/manitou/config.yaml

# Adding a new client:
# 1. Create clients/{name}/config.yaml
# 2. Define specs and transforms
# 3. Run the CLI or let the GitHub Action handle it

First Client: Manitou

• 25 source specs → 27 output files (Catalog splits 3 ways, Orders splits 4 ways)
• Config: clients/manitou/config.yaml

GitHub Action

• Triggers on PRs touching source specs (VTEX - *.json), client configs, or tool source
• Installs dependencies, runs the CLI for all clients/*/config.yaml files
• Auto-commits generated output back to the PR branch

Testing

• 63 unit tests covering all 8 transforms + pipeline orchestration
• Run locally: cd tools/apim-gen && npm test

Commits

1. Add apim-gen CLI project setup — package.json, tsconfig, vitest config
2. Add apim-gen core types and config loader — foundation types and YAML config parser
3. Add apim-gen OpenAPI transforms — 8 composable transform functions
4. Add apim-gen pipeline and CLI entry point — orchestration and CLI interface
5. Add apim-gen tests — 63 tests across 9 test files
6. Add Manitou client configuration — first client with 25 spec entries
7. Add GitHub Actions workflow for spec generation — CI automation
8. Fix workflow to detect new output files and checkout PR head — fix for untracked file detection

Note: Generated output schemas are NOT included in this PR. The GitHub Action will generate and commit them automatically.

[github-actions]

Thanks for your contribution. The .json file will be checked now with Spectral.