@zenith-payments/oai-transformer

v0.0.3

Published

16 days ago

Download TravelPay Swagger spec and convert to OpenAPI 3.1 with fixes, examples, and links

0High
0Medium
0Low

openapi swagger zenith payments zenpay rentalrewards b2bpay childcareeasypay schooleasypay travelpay thoroughbredpayments

TravelPay Swagger → OpenAPI 3.1 Pipeline

This repository downloads TravelPay’s auto-generated Swagger (OpenAPI 2.0) document and produces two outputs:

openapi/openapi2-fixed.json: Swagger 2.0 after structural fixes + better operation summaries/descriptions.
openapi/openapi3-fixed.json: OpenAPI 3.1 after conversion, example injection, link injection, formatting, validation, and linting.

Every run also generates fix-report.md, which is intended to be the human-readable “audit log” of what changed and why.

The orchestrator is src/pipeline.ts. If you want to understand the behavior end-to-end, read that file first.

Repo Layout

src/pipeline.ts: Runs the entire pipeline and writes fix-report.md.
src/download.ts: Downloads the Swagger 2.0 JSON from the TravelPay “help” endpoint with daily caching.
src/fix.ts: Applies structural fixes to Swagger 2.0 (endpoint removals, security normalization, enum normalization, $ref wrapping) and generates a detailed report.
src/config.ts: Centralized paths + constants (including environments and enum allowlist).
spec/: Download destination for the raw input (spec/openapi2.original.json).
- spec/.cache/: Daily cache + download-status.json metadata.
openapi/: Generated outputs.
- openapi/openapi2.json: A convenience copy of the downloaded spec (download step) and also the fix script’s intermediate output (the pipeline deletes it after copying into openapi2-fixed.json).
- openapi/openapi2-fixed.json: Pipeline output (fixed Swagger 2.0).
- openapi/openapi3-fixed.json: Pipeline output (fixed OpenAPI 3.1).
- openapi/.tmp/: Temporary report directory (created by src/fix.ts, deleted by pipeline).
summary-descriptions.json: Canonical per-operation summaries/descriptions used to replace auto-generated text.
examples/: Request/response captures used for OpenAPI 3.1 example injection.
.spectral.yaml: Spectral ruleset used by the pipeline to lint the generated specs.
HPP-Authorise-Endpoint.yaml: Separate OpenAPI 3.1 spec for the hosted payment page Authorise endpoint (not part of src/pipeline.ts).

Quick Start

Install dependencies and run the full pipeline:

bun install
bun run generate

Run against specific environments:

bun run generate:uat
bun run generate:prod

Pipeline flags:

bun run generate -- --env uat
bun run generate -- --env prod
bun run generate -- --env sandbox
bun run generate -- --force

Run sub-steps for debugging:

bun run download   # downloads only (writes spec + cache + status)
bun run fix        # fix script only (writes intermediate openapi/openapi2.json + tmp report)

GitHub Release Packaging

Build and pack a publishable .tgz for GitHub Releases:

bun run release:pack

Upload the generated zp-swagger2openapi-<version>.tgz to a GitHub Release.

Install directly from the release asset URL:

bun add https://github.com/YourOrg/YourRepo/releases/download/v1.0.0/zp-swagger2openapi-1.0.0.tgz
npm install https://github.com/YourOrg/YourRepo/releases/download/v1.0.0/zp-swagger2openapi-1.0.0.tgz
pnpm add https://github.com/YourOrg/YourRepo/releases/download/v1.0.0/zp-swagger2openapi-1.0.0.tgz
yarn add https://github.com/YourOrg/YourRepo/releases/download/v1.0.0/zp-swagger2openapi-1.0.0.tgz

GitHub Packages (Private npm)

Publish to GitHub Packages (private, no npm publish unless you explicitly run it):

Ensure GITHUB_TOKEN is set (PAT with read:packages/write:packages).
Build + generate files: @zenith-payments/ @zenith-payments/

bun run generate
bun run build

Publish to GitHub Packages:

npm run publish:github

Install from GitHub Packages:

npm install @zenith-payments/oai-transformer
pnpm add @zenith-payments/oai-transformer
yarn add @zenith-payments/oai-transformer

To import packaged assets:

import spec from "@zenith-payments/oai-transformer/openapi.json";
import doc from "@zenith-payments/oai-transformer/docs/payments.md";
import example from "@zenith-payments/oai-transformer/examples/results/SomeExample.json";

How the Pipeline Works

Preflight Cleanup

The pipeline starts by creating openapi/ if needed, then removing prior outputs:

openapi/openapi2-fixed.json
openapi/openapi3-fixed.json
fix-report.md

It then writes a fresh fix-report.md header with a timestamp. This is intentionally destructive: a run is supposed to create a complete, coherent set of outputs.

Step 1: Download Swagger 2.0

File: src/download.ts

Goal: Fetch the Swagger 2.0 JSON from TravelPay’s help endpoint (per environment) and write it to a stable, predictable local path.

Inputs:

Environment selection: uat, prod, sandbox (see API_HELP_URLS in src/config.ts)

Outputs:

spec/openapi2.original.json (canonical “raw download” used by the fix step)
spec/.cache/openapi2.YYYY-MM-DD.json (daily cache file)
spec/.cache/download-status.json (structured status report)
openapi/openapi2.json (a convenience copy of the downloaded Swagger)

Caching behavior:

If today’s cache exists and --force is not set, the network request is skipped and the status report is written with "cached": true.
Old cache files (previous days) are deleted so only “today’s” is retained.

Why this step exists:

The upstream spec can change frequently; caching makes runs deterministic and avoids unnecessary churn.
The download-status.json captures timing, size, status code, and whether the run was cached, which helps with debugging.

Step 2: Fix the Swagger 2.0 Spec

File: src/fix.ts (invoked by src/pipeline.ts)

Goal: Repair invalid or tool-hostile constructs in the upstream Swagger 2.0 document so it can be cleanly upgraded and consumed by tooling (docs, codegen, testing).

Inputs:

spec/openapi2.original.json

Intermediate outputs (created by the fix script):

openapi/openapi2.json (intermediate fixed Swagger)
openapi/.tmp/fix-report.md (intermediate report with detailed tables)

Final outputs (produced by the pipeline from the intermediate outputs):

openapi/openapi2-fixed.json (the intermediate openapi/openapi2.json, copied/renamed then deleted)
fix-report.md (the pipeline merges the fix script report into the main report)

The fixes are not “generic formatting”; they are specific, targeted transformations. In src/fix.ts, the key behaviors are:

2.1 Remove invalid operations (empty or missing `responses`)

An operation must have at least one response. The fix script treats these as invalid:

missing responses
responses not an object
responses: {}

Those operations are removed from paths.{path}.{method}. If a path ends up containing no operations afterward, the entire paths.{path} entry is removed.

Why remove them?

Leaving an invalid operation breaks validators and downstream tooling.
Guessing fake responses is misleading.
The report includes “how to fix upstream if you want to keep it” guidance.

This is where removals like GET /v2/sessions/{sessionId} happen (see the report snapshot in Appendix B).

2.2 Require Api-Key AND Basic auth

The API requires both an API key header and Basic Auth credentials.

The fix script:

Ensures a Basic entry exists in Swagger 2.0 securityDefinitions.
Ensures operations that use Api-Key also include Basic:
- If an operation has no security, it sets security to:
```
[{ "Api-Key": [], "Basic": [] }]
```
- If an operation has security entries and one contains "Api-Key", it adds "Basic": [] to that same entry.
- If "Basic" is already present anywhere, it does nothing.

Why do this here (instead of just documenting it)?

Generated clients and API docs need to accurately represent authentication requirements, otherwise consumers follow the docs and still get auth failures.

2.3 Normalize “enum-like” properties into `x-enumNames`

The upstream Swagger includes non-standard “enum-ish” properties that look like:

AutoPay: 22; EmailReminder: 23; SmsReminder: 24

…embedded as a property with a name like PaymentOption. This is not valid OpenAPI schema.

The fix script:

Looks for a known allowlist of invalid properties (INVALID_ENUM_PROPERTIES in src/config.ts).
Parses the left-hand side of each name: value pair into an array of display names.
Writes x-enumNames: [...].
Deletes the invalid property entirely.

Where it applies:

operation parameters (including items for array parameters)
response schema blocks
model definitions (definitions.*) and nested schema objects

The current allowlist is:

CustomerMerchantStatus
CreditRequestResponseStatus
PaymentOption
PaymentFrequency
NotificationMethod
TransactionType
RefundValue
OverrideFeePayer
OnlinePaymentVersion
PaymentMode
UserMode
PluginDisplayMode
PaymentSettlement

Why x-enumNames?

It preserves human-friendly names in a way many OpenAPI tools understand.
It turns invalid input into predictable output without inventing behavior.

2.4 Wrap `$ref` siblings using `allOf`

Many tools (especially OpenAPI 3.0.x oriented ones) reject $ref objects with siblings (like $ref + description).

The fix script converts:

{ "$ref": "#/definitions/SomeModel", "description": "..." }

into:

{ "allOf": [{ "$ref": "#/definitions/SomeModel" }], "description": "..." }

Why do this even though the end target is OpenAPI 3.1?

Toolchains (converters, validators, bundlers) often enforce 3.0-era constraints even when outputting 3.1.
This preserves sibling metadata and reduces upgrade friction.

2.5 JSON output normalization

After transformations, src/fix.ts JSON-stringifies the document and replaces Unicode en-dash/em-dash characters with - to avoid downstream parsing/display surprises.

Step 3: Standardize Summaries/Descriptions

File: src/pipeline.ts (uses summary-descriptions.json)

Goal: Replace auto-generated or inconsistent summaries/descriptions with canonical, human-readable text.

Inputs:

openapi/openapi2-fixed.json
summary-descriptions.json

Mechanics:

summary-descriptions.json is grouped by tag, but matching is done by { method, path }.
For every operation in paths, the pipeline finds a matching pattern:
- If found, it overwrites summary and description.
- If not found, it records the operation under “Not Covered” and leaves it unchanged.

Why this exists:

Upstream summaries like BatchPayments_Post are not useful to humans.
Consistent operation naming improves docs and codegen output.

Where to change behavior:

Edit summary-descriptions.json, re-run the pipeline, and inspect the Step 3 tables in fix-report.md.

Step 4: Upgrade to OpenAPI 3.1

File: src/pipeline.ts (calls @scalar/cli)

Goal: Convert the fixed Swagger 2.0 spec into OpenAPI 3.1.

Command executed:

scalar document upgrade openapi/openapi2-fixed.json --output openapi/openapi3-fixed.json

How the pipeline finds scalar:

Under Bun: executes scalar directly (Bun can resolve local bins).
Under Node: prefers node_modules/.bin/scalar when present; otherwise falls back to bunx scalar ... (requires Bun).

Why Scalar:

It provides a robust Swagger → OpenAPI upgrade implementation without maintaining our own converter.

Step 5: Inject Real Examples

File: src/pipeline.ts (reads JSON captures under examples/)

Goal: Attach real request/response examples to the OpenAPI 3.1 document to improve documentation and consumer understanding.

Input file format (examples/*.json):

{
  "request": {
    "method": "GET",
    "url": "https://.../v2/payments/123",
    "body": {}
  },
  "response": { "status": 200, "body": {} }
}

Matching:

The pipeline extracts the URL pathname from request.url.
It matches the concrete path to a spec template path:
- exact match first
- then “template match” allowing {param} placeholders to match concrete segments

Write locations in OpenAPI 3.1:

Request example → requestBody.content["application/json"].example
Response example → responses.{status}.content["application/json"].example

Prep/setup files:

Some captures exist only to create prerequisites for other captures (e.g., create a customer used later).
These are explicitly excluded from injection by filename:
- examples/customers-post-for-batch.json
- examples/customers-payment-option-put-batch.json
- examples/preauths-post-for-capture.json
- examples/preauths-post-for-void.json

Coverage tracking:

examples/API_CALLS.md is a checklist mapping endpoints → example files (Appendix A).

Step 6: Inject OpenAPI Links

File: src/pipeline.ts

Goal: Add OpenAPI Links so stateful testing tools (notably Schemathesis) can navigate from “create” responses to “read/update/delete” endpoints automatically.

High-level algorithm:

Enumerate all operations and record which path parameters they consume.
For each POST/PUT operation:
- find a success response (POST prefers 201 then 200; PUT prefers 200)
- ensure the success response has JSON schema properties
- look for “ID fields” in those properties (below)
For each discovered ID field, find operations that consume that same field as a path parameter.
Add responses.{status}.links.{linkName} pointing to the consumer operationId, passing the parameter from $response.body#/field.

ID fields considered today:

batchPaymentId
cardProxy
customerReference
paymentReference
preauthReference
requestPayId
refundRequestUniqueId
proxy
sessionId

Cross-resource linking:

Some operations return IDs that should link to other resources (e.g., capturing a preauth returns a paymentReference that should link to Payments operations). These are hard-coded in src/pipeline.ts as CROSS_RESOURCE_LINKS.

Link naming:

Link names are derived from the target operationId with underscores removed (e.g., Payments_GetPayment → PaymentsGetPayment).

Step 7: Format the Specs

File: src/pipeline.ts (calls @scalar/cli)

Commands:

scalar document format openapi/openapi2-fixed.json
scalar document format openapi/openapi3-fixed.json

Behavior:

Formatting failures are logged as warnings, but the pipeline continues. Formatting is a “nice to have” for diff stability, not a correctness gate.

Step 8: Validate the Specs

File: src/pipeline.ts (calls @scalar/cli)

Commands:

scalar document validate openapi/openapi2-fixed.json
scalar document validate openapi/openapi3-fixed.json

Behavior:

The pipeline prints a table in the console (VALID vs error count + first message).
The results are appended to fix-report.md.

Step 9: Lint with Spectral

File: src/pipeline.ts (Spectral JS API + .spectral.yaml)

Goal: Apply best-practice and project-specific linting to both generated specs.

Implementation details:

Uses @stoplight/spectral-core programmatically (not the CLI).
Loads .spectral.yaml via @stoplight/spectral-ruleset-bundler/with-loader.

Ruleset highlights (.spectral.yaml):

Extends spectral:oas with all enabled, then selectively disables/downgrades rules that don’t fit an auto-generated-spec workflow.
Enforces strict correctness rules like:
- operation-success-response (error): requires a 2xx/3xx response
- operation-operationId and operation-operationId-unique (error)
- typed-enum and path-params (error)
Adds custom project rules, including:
- x-enumNames-is-array (error): ensures x-enumNames is a non-empty string array
- operationId-pascal-underscore (hint): encourages Resource_Action naming
- no-empty-description (warn): prohibits empty-string descriptions

What Changes vs Upstream

There are two kinds of “change” in this repo:

Structural fixes (Step 2) that keep the spec valid and tool-compatible:
- Removing invalid operations with empty/missing responses (e.g., GET /v2/sessions/{sessionId}).
- Enforcing Basic + Api-Key security.
- Converting invalid “enum-like” properties into x-enumNames.
- Wrapping $ref siblings into allOf.
Documentation enrichment (Steps 3, 5, 6) that improves usability:
- Human-readable summaries/descriptions for all covered operations.
- Real request/response examples injected into the OpenAPI 3.1 output.
- OpenAPI Links for stateful navigation and testing.

The authoritative, run-specific list of changes is fix-report.md. It is regenerated on each run.

How to Extend the Pipeline

Add a new standardized summary/description

Add an entry in summary-descriptions.json under the appropriate tag.
Re-run bun run generate.
Confirm the operation appears as updated under Step 3 in fix-report.md.

Add a new request/response example

Create a new capture file in examples/ using the { request, response } format.
Prefer real URLs with concrete IDs; the pipeline will template-match them.
Re-run bun run generate.
Confirm the example was applied (the pipeline reports applied vs skipped).
Update examples/API_CALLS.md so coverage stays visible.

Add another enum-like property to normalize

Add the property name to INVALID_ENUM_PROPERTIES in src/config.ts.
Re-run bun run generate.
Confirm the conversion table in fix-report.md includes the new property instances.

Add or adjust OpenAPI Links behavior

Update LINK_ID_FIELDS and/or CROSS_RESOURCE_LINKS in src/pipeline.ts.
Re-run bun run generate.
Inspect openapi/openapi3-fixed.json under responses.*.links and the Step 6 section in fix-report.md.

Appendix A: Example Coverage Checklist

This is copied from examples/API_CALLS.md and exists to ensure we have “real capture” examples for every important endpoint.

| Status | Method | Endpoint | Example File(s) | | ------ | ------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | ✅ | POST | /v2/batchpayments | batchpayments-post.json | | ✅ | GET | /v2/batchpayments/{batchPaymentId} | batchpayments-get.json | | ✅ | GET | /v2/batchpayments/{batchPaymentId}/entries | batchpayments-entries-get.json | | ✅ | POST | /v2/cardproxies | cardproxies-post.json | | ✅ | DELETE | /v2/cardproxies/{cardProxy} | cardproxies-delete.json | | ✅ | GET | /v2/cardproxies/{cardProxy} | cardproxies-get.json | | ✅ | GET | /v2/cardproxies/{cardProxy}/pricing | cardproxies-pricing.json | | ✅ | GET | /v2/customers | customers-get.json | | ✅ | POST | /v2/customers | customers-post.json, customers-post-for-batch.json | | ✅ | GET | /v2/customers/{customerReference} | customers-get-by-ref.json | | ✅ | GET | /v2/customers/{customerReference}/account | customers-account-get.json | | ✅ | PUT | /v2/customers/{customerReference}/account | customers-account-put.json | | ✅ | PUT | /v2/customers/{customerReference}/customerReference | customers-ref-update.json | | ✅ | GET | /v2/customers/{customerReference}/paymentOption | customers-payment-option-get.json | | ✅ | PUT | /v2/customers/{customerReference}/paymentOption | customers-payment-option-put.json, customers-payment-option-put-batch.json | | ✅ | GET | /v2/customers/{customerReference}/profile | customers-profile-get.json | | ✅ | PUT | /v2/customers/{customerReference}/profile | customers-profile-put.json | | ✅ | GET | /v2/customers/{customerReference}/status | customers-status-get.json | | ✅ | PUT | /v2/customers/{customerReference}/status | customers-status-put.json | | ✅ | GET | /v2/diagnostics/ping | diagnostics-ping.json | | ✅ | GET | /v2/payments | payments-get.json | | ✅ | POST | /v2/payments | payments-post-customer.json, payments-post-proxy.json | | ✅ | GET | /v2/payments/{paymentReference} | payments-get-by-ref.json | | ✅ | GET | /v2/payments/uniqueId/{merchantUniqueId} | payments-get-by-merchant-unique-id.json | | ✅ | GET | /v2/payments/{paymentReference}/refundrequests | payments-refundrequests-get.json | | ✅ | POST | /v2/payments/{paymentReference}/refundrequests | payments-refundrequests-post.json | | ✅ | GET | /v2/payments/uniqueId/{paymentReference}/refundrequests/{refundRequestUniqueId} | payments-refundrequests-get-by-uniqueid.json | | ✅ | GET | /v2/preauths | preauths-get.json | | ✅ | POST | /v2/preauths | preauths-post.json, preauths-post-for-capture.json, preauths-post-for-void.json | | ✅ | GET | /v2/preauths/{preauthReference} | preauths-get-by-ref.json | | ✅ | POST | /v2/preauths/{preauthReference}/captures | preauths-capture-post.json | | ✅ | PUT | /v2/preauths/{preauthReference}/voids | preauths-void-put.json | | ✅ | GET | /v2/proxies/{proxy} | proxies-get.json | | ✅ | GET | /v2/proxies/{proxy}/pricing | proxies-pricing.json | | ✅ | POST | /v2/requestpays | requestpays-post.json | | ✅ | GET | /v2/requestpays/{requestPayId} | requestpays-get.json | | ✅ | GET | /v2/requestpays/{requestPayId}/entries | requestpays-entries-get.json | | ✅ | POST | /v2/sessions | sessions-post.json |

Prep files (excluded from injection):

customers-post-for-batch.json
customers-payment-option-put-batch.json
preauths-post-for-capture.json
preauths-post-for-void.json

Appendix B: fix-report.md Snapshot

This is a snapshot of fix-report.md from the current workspace. It is regenerated on every run; do not treat it as permanent documentation of the upstream API, but rather as the record of “what this pipeline did on that run”.

# OpenAPI Pipeline Report

Generated: 2026-01-21T16:09:22.535Z

## This report documents all transformations applied to the TravelPay API specification.

## Step 1: Download Swagger 2.0

**Tool:** fetch (via 1-download-travelpay-swagger.ts)

| Parameter   | Value                                                |
| ----------- | ---------------------------------------------------- |
| Script      | `src/download.ts`                                    |
| Environment | UAT                                                  |
| Output      | `F:\_ZP-Swagger2OpenAPI\spec\openapi2.original.json` |
| Status      | CACHED (hash unchanged)                              |

---

## Step 2: Apply Fixes

**Tool:** 2-fix-openapi2-spec-v2.ts (simplified fix pipeline)

| Parameter | Value                                                |
| --------- | ---------------------------------------------------- |
| Input     | `F:\_ZP-Swagger2OpenAPI\spec\openapi2.original.json` |
| Script    | `src/fix.ts`                                         |
| Output    | `F:\_ZP-Swagger2OpenAPI\openapi\openapi2-fixed.json` |

## Removed Operations

**Why:** The OpenAPI spec requires every operation to have at least one response defined.
Operations with empty `responses: {}` are invalid and cause validation errors.

**How to fix (if you want to keep the endpoint):** Add a response to the original API spec:

```json
"responses": {
  "200": { "description": "Success" },
  "404": { "description": "Not found" }
}
```

| Method | Path                       | Reason          |
| ------ | -------------------------- | --------------- |
| GET    | `/v2/sessions/{sessionId}` | empty responses |

---

## Security Changes

**What:** Added Basic authentication requirement alongside Api-Key.

**Why:** The API requires both Api-Key header AND Basic auth credentials.

**Before:**

```json
"security": [{ "Api-Key": [] }]
```

**After:**

```json
"security": [{ "Api-Key": [], "Basic": [] }]
```

- Security definition added: Yes
- Operations updated: 40

---

## Enum Property Conversions

**Why:** The original spec uses non-standard properties like `PaymentOption`, `PaymentFrequency`
with string values like `"AutoPay: 22; EmailReminder: 23"`. These are not valid OpenAPI.

**What we did:** Converted to standard `x-enumNames` extension arrays.

| Location                                        | Property                      | Before                                                                                                                                                                            | After                                                                                                                                                              |
| ----------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `paths./v2/customers.get.parameters[1].items`   | `CustomerMerchantStatus`      | `Open: 0; AwaitingEmailVerfication: 1; AwaitingSignature: 2; SetUpIncomplete: 3; Restricted: 4; Closed: 5; OnHold: 6; PendingBankAccountVerification: 7; ReferCustomerAccount: 8` | `["Open","AwaitingEmailVerfication","AwaitingSignature","SetUpIncomplete","Restricted","Closed","OnHold","PendingBankAccountVerification","ReferCustomerAccount"]` |
| `paths./v2/customers.get.parameters[6].items`   | `PaymentOption`               | `AutoPay: 22; EmailReminder: 23; SmsReminder: 24; FixedTerm: 25; BatchPay: 26; ScheduledPay: 27; OneOff: 28; PayID: 148; BPAY: 149`                                               | `["AutoPay","EmailReminder","SmsReminder","FixedTerm","BatchPay","ScheduledPay","OneOff","PayID","BPAY"]`                                                          |
| `paths./v2/payments.get.parameters[4]`          | `PaymentSettlement`           | `All: 0; Settled: 1; NotSettled: 2`                                                                                                                                               | `["All","Settled","NotSettled"]`                                                                                                                                   |
| `paths./v2/payments.get.parameters[5].items`    | `TransactionType`             | `Charge: 1; InvoicePayment: 2; Refund: 3; Chargeback: 4; Recall: 5; FixedTermSettlement: 6`                                                                                       | `["Charge","InvoicePayment","Refund","Chargeback","Recall","FixedTermSettlement"]`                                                                                 |
| `...ns.CreditRequestResponse.properties.status` | `CreditRequestResponseStatus` | `Forbidden: 0; CountLimitReached: 1; AmountLimitReached: 2; InvalidPaymentProxy: 3; DuplicateRequest: 4; NotEligibleForCredit: 5; Success: 6`                                     | `["Forbidden","CountLimitReached","AmountLimitReached","InvalidPaymentProxy","DuplicateRequest","NotEligibleForCredit","Success"]`                                 |
| `...omerPaymentOption.properties.paymentOption` | `PaymentOption`               | `AutoPay: 22; EmailReminder: 23; SmsReminder: 24; FixedTerm: 25; BatchPay: 26; ScheduledPay: 27; OneOff: 28; PayID: 148; BPAY: 149`                                               | `["AutoPay","EmailReminder","SmsReminder","FixedTerm","BatchPay","ScheduledPay","OneOff","PayID","BPAY"]`                                                          |
| `...rPaymentOption.properties.paymentFrequency` | `PaymentFrequency`            | `Weekly: 32; Fortnightly: 33; Monthly: 34; Quarterly: 35; HalfYearly: 36; Yearly: 37; FourWeeks: 38`                                                                              | `["Weekly","Fortnightly","Monthly","Quarterly","HalfYearly","Yearly","FourWeeks"]`                                                                                 |
| `...aymentOption.properties.notificationMethod` | `NotificationMethod`          | `None: 0; Sms: 1; Email: 2`                                                                                                                                                       | `["None","Sms","Email"]`                                                                                                                                           |
| `...tions.NewCustomer.properties.paymentOption` | `PaymentOption`               | `AutoPay: 22; EmailReminder: 23; SmsReminder: 24; FixedTerm: 25; BatchPay: 26; ScheduledPay: 27; OneOff: 28; PayID: 148; BPAY: 149`                                               | `["AutoPay","EmailReminder","SmsReminder","FixedTerm","BatchPay","ScheduledPay","OneOff","PayID","BPAY"]`                                                          |
| `...ns.NewCustomer.properties.paymentFrequency` | `PaymentFrequency`            | `Weekly: 32; Fortnightly: 33; Monthly: 34; Quarterly: 35; HalfYearly: 36; Yearly: 37; FourWeeks: 38`                                                                              | `["Weekly","Fortnightly","Monthly","Quarterly","HalfYearly","Yearly","FourWeeks"]`                                                                                 |
| `....NewCustomer.properties.notificationMethod` | `NotificationMethod`          | `None: 0; Sms: 1; Email: 2`                                                                                                                                                       | `["None","Sms","Email"]`                                                                                                                                           |
| `...wCustomerResponse.properties.paymentOption` | `PaymentOption`               | `AutoPay: 22; EmailReminder: 23; SmsReminder: 24; FixedTerm: 25; BatchPay: 26; ScheduledPay: 27; OneOff: 28; PayID: 148; BPAY: 149`                                               | `["AutoPay","EmailReminder","SmsReminder","FixedTerm","BatchPay","ScheduledPay","OneOff","PayID","BPAY"]`                                                          |
| `...stomerResponse.properties.paymentFrequency` | `PaymentFrequency`            | `Weekly: 32; Fortnightly: 33; Monthly: 34; Quarterly: 35; HalfYearly: 36; Yearly: 37; FourWeeks: 38`                                                                              | `["Weekly","Fortnightly","Monthly","Quarterly","HalfYearly","Yearly","FourWeeks"]`                                                                                 |
| `...omerResponse.properties.notificationMethod` | `NotificationMethod`          | `None: 0; Sms: 1; Email: 2`                                                                                                                                                       | `["None","Sms","Email"]`                                                                                                                                           |
| `...PaymentResponse.properties.transactionType` | `TransactionType`             | `Charge: 1; InvoicePayment: 2; Refund: 3; Chargeback: 4; Recall: 5; FixedTermSettlement: 6`                                                                                       | `["Charge","InvoicePayment","Refund","Chargeback","Recall","FixedTermSettlement"]`                                                                                 |
| `...ions.RefundResponse.properties.refundValue` | `RefundValue`                 | `Base: 1; Partial: 2; Full: 3`                                                                                                                                                    | `["Base","Partial","Full"]`                                                                                                                                        |
| `...tions.RefundRequest.properties.refundValue` | `RefundValue`                 | `Base: 1; Partial: 2; Full: 3`                                                                                                                                                    | `["Base","Partial","Full"]`                                                                                                                                        |
| `...PaymentRequest.properties.overrideFeePayer` | `OverrideFeePayer`            | `Default: 0; Merchant: 1; Customer: 2`                                                                                                                                            | `["Default","Merchant","Customer"]`                                                                                                                                |
| `...PreauthResponse.properties.transactionType` | `TransactionType`             | `Charge: 1; InvoicePayment: 2; Refund: 3; Chargeback: 4; Recall: 5; FixedTermSettlement: 6`                                                                                       | `["Charge","InvoicePayment","Refund","Chargeback","Recall","FixedTermSettlement"]`                                                                                 |
| `...PreauthRequest.properties.overrideFeePayer` | `OverrideFeePayer`            | `Default: 0; Merchant: 1; Customer: 2`                                                                                                                                            | `["Default","Merchant","Customer"]`                                                                                                                                |
| `...ureCardResponse.properties.transactionType` | `TransactionType`             | `Charge: 1; InvoicePayment: 2; Refund: 3; Chargeback: 4; Recall: 5; FixedTermSettlement: 6`                                                                                       | `["Charge","InvoicePayment","Refund","Chargeback","Recall","FixedTermSettlement"]`                                                                                 |
| `definitions.SessionRequest.properties.version` | `OnlinePaymentVersion`        | `v1: 1; v2: 2; v3: 3; v4: 4; v5: 5`                                                                                                                                               | `["v1","v2","v3","v4","v5"]`                                                                                                                                       |
| `definitions.SessionRequest.properties.mode`    | `PaymentMode`                 | `DefaultPayment: 0; Tokenise: 1; CustomPayment: 2; Preauth: 3`                                                                                                                    | `["DefaultPayment","Tokenise","CustomPayment","Preauth"]`                                                                                                          |
| `...nitions.SessionRequest.properties.userMode` | `UserMode`                    | `Customer: 0; Merchant: 1`                                                                                                                                                        | `["Customer","Merchant"]`                                                                                                                                          |
| `...ions.SessionRequest.properties.displayMode` | `PluginDisplayMode`           | `Default: 0; RedirectUrl: 1`                                                                                                                                                      | `["Default","RedirectUrl"]`                                                                                                                                        |
| `...SessionRequest.properties.overrideFeePayer` | `OverrideFeePayer`            | `Default: 0; Merchant: 1; Customer: 2`                                                                                                                                            | `["Default","Merchant","Customer"]`                                                                                                                                |

---

## $ref Sibling Fixes

**Why:** In OpenAPI 3.0.x, a `$ref` cannot have sibling properties (like `description`).
This is valid in 3.1, but not in 3.0.x.

**What we did:** Wrapped the `$ref` in an `allOf` array so siblings are preserved.

**Before:**

```json
{
  "$ref": "#/definitions/SomeModel",
  "description": "Some description"
}
```

**After:**

```json
{
  "allOf": [{ "$ref": "#/definitions/SomeModel" }],
  "description": "Some description"
}
```

| Location                                   | $ref                      | Sibling Properties |
| ------------------------------------------ | ------------------------- | ------------------ |
| `definitions.ModelState.properties.value`  | `ValueProviderResult`     | description        |
| `...ns.PricingResponse.properties.pricing` | `Pricing`                 | description        |
| `...xyRequest.properties.threeDSecureData` | `ThreeDSecureData`        | description        |
| `...reeDSecureData.properties.browserData` | `ThreeDSecureBrowserData` | description        |
| `....CardProxyResponse.properties.pricing` | `Pricing`                 | description        |
| `...s.CustomerResponse.properties.profile` | `CustomerProfile`         | description        |
| `...s.CustomerResponse.properties.account` | `CustomerAccountResponse` | description        |
| `...omerResponse.properties.paymentOption` | `CustomerPaymentOption`   | description        |
| `...rPaymentOption.properties.payIdDetail` | `PayIdDetail`             | description        |
| `...erPaymentOption.properties.bPayDetail` | `BPayDetail`              | description        |
| `...AccountRequest.properties.bankAccount` | `BankAccount`             | description        |
| `...untRequest.properties.creditCardProxy` | `CreditCardProxy`         | description        |
| `...equest.properties.paymentAccountProxy` | `AccountProxy`            | description        |
| `...itions.NewCustomer.properties.address` | `CustomerAddress`         | description        |
| `...ns.NewCustomer.properties.bankAccount` | `BankAccount`             | description        |
| `definitions.NewCustomer.properties.card`  | `CreditCardProxy`         | description        |
| `...stomer.properties.paymentAccountProxy` | `AccountProxy`            | description        |
| `...stomerResponse.properties.payIdDetail` | `PayIdDetail`             | description        |
| `...ustomerResponse.properties.bPayDetail` | `BPayDetail`              | description        |
| `...ewCustomerResponse.properties.address` | `CustomerAddress`         | description        |
| `...stomerResponse.properties.bankAccount` | `BankAccount`             | description        |
| `...s.NewCustomerResponse.properties.card` | `CreditCardProxy`         | description        |
| `...sponse.properties.paymentAccountProxy` | `AccountProxy`            | description        |
| `...roperties.settlementPostPartialRefund` | `SettlementPayment`       | description        |
| `...equest.properties.paymentAccountProxy` | `AccountProxy`            | description        |
| `...itions.PaymentRequest.properties.card` | `PaymentCard`             | description        |
| `...ntRequest.properties.threeDSecureData` | `ThreeDSecureData`        | description        |
| `...equest.properties.paymentAccountProxy` | `AccountProxy`            | description        |
| `...itions.PreauthRequest.properties.card` | `PaymentCard`             | description        |
| `...thRequest.properties.threeDSecureData` | `ThreeDSecureData`        | description        |
| `...uest.properties.allowedPaymentMethods` | `PluginPaymentMethods`    | description        |
| `...ssionRequest.properties.customization` | `PluginCustomization`     | description        |

---

## Step 3: Standardize Summaries/Descriptions

**Tool:** inline summary/description standardization

| Parameter | Value                                                |
| --------- | ---------------------------------------------------- |
| Input     | `F:\_ZP-Swagger2OpenAPI\openapi\openapi2-fixed.json` |
| Patterns  | 40 operations                                        |

**Why:** The original spec has auto-generated summaries like `"BatchPayments_Post"` and
descriptions like `"Batchpayments Post"`. These are not user-friendly.

### Summary

| Metric      | Count |
| ----------- | ----- |
| Updated     | 40    |
| Unchanged   | 0     |
| Not Covered | 0     |

### BatchPayments

| Method | Path                                  | Before Summary                                                                               | After Summary                                | Before Description | After Description                                               |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------ | --------------------------------------------------------------- |
| GET    | `/v2/batchpayments/{batchPaymentId}`  | Get the batch payment summary.                                                               | Get Batch Payment by batchPaymentId          | (empty)            | Returns batch payment details for the specified batchPaymentId. |
| GET    | `...ayments/{batchPaymentId}/entries` | Method return all the Batch payment transactions based on batch payment id                   | List Batch Payment Entries by batchPaymentId | (empty)            | Returns batch payment entries for the specified batchPaymentId. |
| POST   | `/v2/batchpayments`                   | This Method will be return to upload payments batch as a collection of json and process them | Create Batch Payment                         | (empty)            | Creates a batch payment from the provided batch entries.        |

### CardProxies

| Method                                     | Path                                  | Before Summary                                                                                                                                                                        | After Summary                                                           | Before Description | After Description                                              |
| ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------- |
| GET                                        | `/v2/cardproxies/{cardProxy}`         | Get card proxy detail                                                                                                                                                                 | Get Card Proxy by cardProxy                                             | (empty)            | Returns card proxy details for the specified cardProxy.        |
| DELETE                                     | `/v2/cardproxies/{cardProxy}`         | Delete card proxy permanently from the system. This will not affect                                                                                                                   |
| any customer, registered using this proxy. | Delete Card Proxy by cardProxy        | (empty)                                                                                                                                                                               | Deletes the specified cardProxy. This does not affect linked customers. |
| GET                                        | `/v2/cardproxies/{cardProxy}/pricing` | Get pricing for card proxy and payment amount                                                                                                                                         | Get Card Proxy Pricing by cardProxy                                     | (empty)            | Returns pricing for the specified cardProxy and paymentAmount. |
| POST                                       | `/v2/cardproxies`                     | Generate card proxy. Not recommended for software / sites that are not PCI DSS compliant. For an easy and secure card tokenisation and payment option, see our Payment Plugin jQuery. | Create Card Proxy                                                       | (empty)            | Creates a card proxy using the provided card details.          |

### CreditRequests

| Method | Path                                  | Before Summary        | After Summary                         | Before Description | After Description                                                 |
| ------ | ------------------------------------- | --------------------- | ------------------------------------- | ------------------ | ----------------------------------------------------------------- |
| GET    | `...redit-requests/{requestUniqueId}` | (empty)               | Get Credit Request by requestUniqueId | (empty)            | Returns credit request details for the specified requestUniqueId. |
| POST   | `/v2/credit-requests`                 | Create credit request | Create Credit Request                 | (empty)            | Creates a credit request using the provided details.              |

### Customers

| Method | Path                                  | Before Summary                                             | After Summary                                       | Before Description | After Description                                                   |
| ------ | ------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
| GET    | `/v2/customers/{customerReference}`   | Return the customer using the provided customer reference. | Get Customer by customerReference                   | (empty)            | Returns customer details for the specified customerReference.       |
| GET    | `...omers/{customerReference}/status` | Get Customer status                                        | Get Customer Status by customerReference            | (empty)            | Returns status details for the specified customerReference.         |
| PUT    | `...omers/{customerReference}/status` | Update the customer status                                 | Update Customer Status by customerReference         | (empty)            | Updates status details for the specified customerReference.         |
| GET    | `...mers/{customerReference}/account` | Get Customer credit / debit card or bank account           | Get Customer Account by customerReference           | (empty)            | Returns account details for the specified customerReference.        |
| PUT    | `...mers/{customerReference}/account` | Update the customer account                                | Update Customer Account by customerReference        | (empty)            | Updates the account for the specified customerReference.            |
| GET    | `...mers/{customerReference}/profile` | Get Customer profile                                       | Get Customer Profile by customerReference           | (empty)            | Returns profile details for the specified customerReference.        |
| PUT    | `...mers/{customerReference}/profile` | Update the customer profile.                               | Update Customer Profile by customerReference        | (empty)            | Updates profile details for the specified customerReference.        |
| GET    | `...customerReference}/paymentOption` | Get Customer payment option                                | Get Customer Payment Option by customerReference    | (empty)            | Returns payment options for the specified customerReference.        |
| PUT    | `...customerReference}/paymentOption` | Update the customer payment option                         | Update Customer Payment Option by customerReference | (empty)            | Updates payment options for the specified customerReference.        |
| GET    | `/v2/customers`                       | Return customers based on the filter provided.             | List Customers                                      | (empty)            | Returns customers matching the provided filters.                    |
| POST   | `/v2/customers`                       | Create customer using the provided details                 | Create Customer                                     | (empty)            | Creates a customer using the provided details.                      |
| PUT    | `...omerReference}/customerReference` | Update the customer reference                              | Update Customer Reference by customerReference      | (empty)            | Updates the customer reference for the specified customerReference. |

### Diagnostics

| Method | Path                   | Before Summary                                                  | After Summary | Before Description | After Description                              |
| ------ | ---------------------- | --------------------------------------------------------------- | ------------- | ------------------ | ---------------------------------------------- |
| GET    | `/v2/diagnostics/ping` | Ping method to get the server date time and version information | Ping          | (empty)            | Ping the API to check if it is up and running. |

### Payments

| Method | Path                                  | Before Summary                                                                              | After Summary                               | Before Description | After Description                                                                                              |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------- |
| GET    | `/v2/payments/{paymentReference}`     | Returns Payment details based on Payment reference                                          | Get Payment by paymentReference             | (empty)            | Returns payment details for the specified paymentReference.                                                    |
| GET    | `...ents/uniqueId/{merchantUniqueId}` | Returns Payment details based on merchant unique reference                                  | Get Payment by merchantUniqueId             | (empty)            | Returns payment details for the specified merchantUniqueId.                                                    |
| GET    | `...paymentReference}/refundrequests` | Returns all the refund requests details based on payment reference                          | List Refund Requests by paymentReference    | (empty)            | Returns refund requests for the specified paymentReference.                                                    |
| POST   | `...paymentReference}/refundrequests` | Allow the merchant to request for refund for provided payment using payment reference.      | Create Refund Request by paymentReference   | (empty)            | Creates a refund request for the specified paymentReference.                                                   |
| GET    | `...requests/{refundRequestUniqueId}` | (empty)                                                                                     | Get Refund Request by refundRequestUniqueId | (empty)            | Returns refund request details for the specified refundRequestUniqueId.                                        |
| GET    | `/v2/payments`                        | (empty)                                                                                     | List Payments                               | (empty)            | Returns payments matching the provided filters.                                                                |
| POST   | `/v2/payments`                        | Perform OneOff payment for a registered customer with customer reference and payment amount | Create Payment                              | (empty)            | Creates a payment using customerReference or paymentAccountProxy (card/bank) and the provided payment details. |

### Preauths

| Method | Path                                  | Before Summary | After Summary                              | Before Description | After Description                                                                                               |
| ------ | ------------------------------------- | -------------- | ------------------------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| GET    | `/v2/preauths/{preauthReference}`     | (empty)        | Get Preauth by preauthReference            | (empty)            | Returns preauthorization details for the specified preauthReference.                                            |
| GET    | `/v2/preauths`                        | (empty)        | List Preauths                              | (empty)            | Returns preauthorization requests matching the provided filters.                                                |
| POST   | `/v2/preauths`                        | (empty)        | Create Preauth                             | (empty)            | Creates a preauthorization using customerReference or paymentAccountProxy (card/bank) and the provided details. |
| PUT    | `...reauths/{preauthReference}/voids` | (empty)        | Update Preauth Void by preauthReference    | (empty)            | Voids the specified preauthorization.                                                                           |
| POST   | `...uths/{preauthReference}/captures` | (empty)        | Create Preauth Capture by preauthReference | (empty)            | Captures the specified preauthorization.                                                                        |

### Proxies

| Method | Path                          | Before Summary                                                       | After Summary              | Before Description | After Description                              |
| ------ | ----------------------------- | -------------------------------------------------------------------- | -------------------------- | ------------------ | ---------------------------------------------- |
| GET    | `/v2/proxies/{proxy}`         | Get the payment information based on the proxy information provided. | Get Proxy by proxy         | (empty)            | Returns proxy details for the specified proxy. |
| GET    | `/v2/proxies/{proxy}/pricing` | Get pricing for card/bank proxy and payment amount                   | Get Proxy Pricing by proxy | (empty)            | Returns pricing for the specified proxy.       |

### RequestPays

| Method | Path                                  | Before Summary                                                                                 | After Summary                            | Before Description | After Description                                                      |
| ------ | ------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
| GET    | `/v2/requestpays/{requestPayId}`      | Api to get the request pay details                                                             | Get Request Pay by requestPayId          | (empty)            | Returns request pay details for the specified requestPayId.            |
| GET    | `...questpays/{requestPayId}/entries` | Api to get the request pay entries                                                             | List Request Pay Entries by requestPayId | (empty)            | Returns request pay entries for the specified requestPayId.            |
| POST   | `/v2/requestpays`                     | This Method will be return to upload request payments as a collection of json and process them | Create Request Pay                       | (empty)            | Creates a request pay batch from the provided request payment entries. |

### Sessions

| Method | Path           | Before Summary                                                                      | After Summary  | Before Description | After Description                         |
| ------ | -------------- | ----------------------------------------------------------------------------------- | -------------- | ------------------ | ----------------------------------------- |
| POST   | `/v2/sessions` | Used to create session for Payment Plugin. The session created will have an expiry. | Create Session | (empty)            | Creates a session for the payment plugin. |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

TravelPay Swagger → OpenAPI 3.1 Pipeline

Table of Contents

Repo Layout

Quick Start

GitHub Release Packaging

GitHub Packages (Private npm)

How the Pipeline Works

Preflight Cleanup

Step 1: Download Swagger 2.0

Step 2: Fix the Swagger 2.0 Spec

2.1 Remove invalid operations (empty or missing responses)

2.2 Require Api-Key AND Basic auth

2.3 Normalize “enum-like” properties into x-enumNames

2.4 Wrap $ref siblings using allOf

2.5 JSON output normalization

Step 3: Standardize Summaries/Descriptions

Step 4: Upgrade to OpenAPI 3.1

Step 5: Inject Real Examples

Step 6: Inject OpenAPI Links

Step 7: Format the Specs

Step 8: Validate the Specs

Step 9: Lint with Spectral

What Changes vs Upstream

How to Extend the Pipeline

Add a new standardized summary/description

Add a new request/response example

Add another enum-like property to normalize

Add or adjust OpenAPI Links behavior

Appendix A: Example Coverage Checklist

Appendix B: fix-report.md Snapshot

2.1 Remove invalid operations (empty or missing `responses`)

2.3 Normalize “enum-like” properties into `x-enumNames`

2.4 Wrap `$ref` siblings using `allOf`