oai-transformer

Keeps a production-ready OpenAPI 3.2 spec in sync with the live ZenPay Swagger 2.0 — without auto-editing the documentation that ships in the spec.

See FLOW.md for the full pipeline diagram, source file inventory, and failure modes.

Quick start

npm install
npm run csv-to-json   # convert maintainer CSVs → generated JSON (commit the output)
npm run start         # run full pipeline → src/downloads/openapi.yaml

Edit a cell in any maintainer CSV, run npm run csv-to-json, then npm run start, and the spec updates immediately.

How CSV becomes the spec

Maintainers own 6 CSV files. npm run csv-to-json turns them into the JSON that Step 4 (4upgrade.ts) reads:

src/maintainer/api-level.tag-descriptions.csv
src/maintainer/operation-level.descriptions-and-summaries.csv
src/maintainer/parameter-level.descriptions.csv              npm run csv-to-json
src/maintainer/operation-level.request-body-descriptions.csv       │
src/maintainer/schema-level.descriptions.csv                       ▼
src/maintainer/schema-property-level.descriptions.csv
        │
        └── csv-to-json.ts (papaparse + zod)
                   │
                   ▼
    src/maintainer/generated/*.json   (committed)
                   │
                   ▼
           4upgrade.ts
                   │
                   ▼
    src/downloads/openapi.yaml

The generated JSONs are committed alongside the CSVs. There is only one source of truth: the CSVs.

CSV schemas

All CSVs use RFC 4180 (comma-delimited, double-quoted when cells contain ,, ", or newlines).

api-level.tag-descriptions.csv · schema-level.descriptions.csv · operation-level.request-body-descriptions.csv

key,value
BatchPayments,Manage Batch Payments.

operation-level.descriptions-and-summaries.csv

operation,summary,description
POST /v2/batchpayments,Create Batch Payment,Creates a batch payment from the provided entries.

parameter-level.descriptions.csv · schema-property-level.descriptions.csv

parent,key,value
GET /v2/customers,customerReference,Customer reference
AccountProxy,label,Label for the account

| Column | Meaning | |---|---| | parent | Tag name, schema name, or METHOD /path | | key | Property name or parameter name | | value | Description text. May contain markdown. |

Contact and server data

addContact and addServers improvements read from src/maintainer/api-level.info.json — not from config.yaml. Edit that file to change the contact details or server list. Toggle enabled: true/false in src/config/config.yaml to control whether they apply.

Seeding maintainer CSVs (one-time)

If src/maintainer/ needs to be repopulated from the current baseline:

npm run generate:csv    # src/baseline/*.json → src/maintainer/*.csv

After the initial seed, maintainers own the CSVs.

Teams webhook setup (one-time)

When drift is detected, the detection workflow POSTs an Adaptive Card to a Power Automate flow that forwards it to a Teams channel.

1. In Teams, open the target channel → ⋯ → Workflows.
2. Select template "Send webhook alerts to a channel".
3. Sign in with a service / shared account. Choose team + channel. Copy the generated URL (shown once).
4. Add as a GitHub repository secret: Settings → Secrets and variables → Actions → New repository secret, name TEAMS_SWAGGER_WEBHOOK_URL.

The sig= query parameter is an HMAC signature — anyone holding the URL can post to your channel. Store only as a GitHub secret. If it leaks, delete the Power Automate flow, recreate from the same template, and update the secret.

Rollback

Teams posting broken:

1. Comment out the Notify Teams step in .github/workflows/swagger-sync.yml.
2. Commit + merge. Falls back to PR-only behaviour; drift-report.md is still committed to the PR.

Detection pipeline needs pausing:

1. Disable the workflow in GitHub → Actions → Swagger Sync → ⋯ → Disable workflow.
2. The publication pipeline (CSVs → spec) keeps working independently.

Bad CSV breaks the pipeline:

1. git restore src/maintainer/ to revert to last-good CSVs.
2. Or edit the CSV directly to fix the syntax error.
3. Rerun npm run csv-to-json and commit.