TypeScript WSDL → SOAP client generator with full xs:attribute support, complex types, sequences, inheritance, and namespace-collision merging.
npm install @techspokes/typescript-wsdl-client







> Transform complex WSDL/XSD definitions into type-safe TypeScript SOAP clients with optional OpenAPI 3.1 specs and production-ready REST gateways.
- ✅ TypeScript-first SOAP clients — Strongly typed, ergonomic client generation from WSDL
- ✅ OpenAPI 3.1 specs — Generate REST API documentation that mirrors your TypeScript types
- ✅ REST gateway over SOAP — Production-ready Fastify handlers with automatic request/response transformation
- ✅ CI-friendly determinism — Stable, diff-friendly output for safe regeneration in version control
- ✅ Predictable modeling — Flattened attributes, consistent $value convention, inheritance resolution
Vendor: TechSpokes · Maintainer: Serge Liatko (@sergeliatko)
---
- Installation
- Quick Start (60 Seconds)
- What You Get (Outputs)
- Core Concepts
- Common Workflows
- Command Reference
- pipeline (Recommended)
- client
- openapi
- gateway
- app
- compile (Advanced)
- Configuration Files
- Working With Generated Clients
- Production Concerns
- Programmatic API
- Troubleshooting
- Contributing
- License
- Support
---
``bash`
npm install --save-dev @techspokes/typescript-wsdl-client
npm install soap # Runtime dependency for SOAP calls
Requirements:
- Node.js 20.0.0 or later
- soap package (runtime dependency for generated clients)
---
Generate a complete SOAP-to-REST stack in one command:
`bash`Generate client, OpenAPI spec, gateway, and runnable app
npx wsdl-tsc pipeline \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir ./tmp/client \
--openapi-file ./tmp/openapi.json \
--gateway-dir ./tmp/gateway \
--gateway-service-name weather \
--gateway-version-prefix v1 \
--generate-app
Start the server:
`bash`
cd tmp/app
cp .env.example .envEdit .env to set WSDL_SOURCE if needed
npx tsx server.js
Test it:
`bashHealth check
curl http://localhost:3000/health
What just happened?
1. Parsed the WSDL and compiled types
2. Generated a TypeScript SOAP client with full type safety
3. Created an OpenAPI 3.1 spec matching the client types
4. Built Fastify gateway handlers that call SOAP and return JSON
5. Created a runnable Express-style app with health/OpenAPI endpoints
---
What You Get (Outputs)
$3
`
client/
├── client.ts # Strongly-typed SOAP client wrapper with methods
├── types.ts # Flattened interfaces, type aliases, and enums
├── utils.ts # Runtime metadata for JSON→SOAP conversion
└── catalog.json # Compiled schema representation (reusable)
`Example usage:
`typescript
import { Weather } from './client/client.js';const client = new Weather({
source: 'https://example.com/weather.wsdl',
});
const result = await client.GetCityWeatherByZIP({ ZIP: '10001' });
console.log(result.GetCityWeatherByZIPResult);
`$3
`
openapi.json # or .yaml — Complete REST API documentation
`- Mirrors exact TypeScript type structure
- All responses wrapped in standard envelope (status, message, data, error)
- Deterministic ordering for version control
- Validates with
swagger-parser by default$3
`
gateway/
├── schemas/
│ ├── models/ # JSON Schema components with URN IDs
│ └── operations/ # Request/response validation schemas
├── routes/ # Route handlers (fully implemented)
├── schemas.ts # Schema registration module
├── routes.ts # Route aggregator
├── runtime.ts # Envelope builders, error handlers
└── plugin.ts # Fastify plugin wrapper
`Example integration:
`typescript
import Fastify from 'fastify';
import weatherGateway from './gateway/plugin.js';
import { Weather } from './client/client.js';const app = Fastify({ logger: true });
const client = new Weather({ source: 'weather.wsdl' });
await app.register(weatherGateway, { client });
await app.listen({ port: 3000 });
`$3
`
app/
├── server.js # Main entry point
├── config.js # Configuration with env var support
├── .env.example # Environment template
├── README.md # Usage instructions
└── openapi.json # OpenAPI spec (when --openapi-mode=copy)
`$3
All gateway responses follow this structure:
Success:
`json
{
"status": "SUCCESS",
"message": null,
"data": { / SOAP response / },
"error": null
}
`Error:
`json
{
"status": "ERROR",
"message": "Request validation failed",
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": { / validation errors / }
}
}
`---
Core Concepts
$3
Attributes and elements become peer properties — No nested wrapper noise:
`xml
``typescript
// Generated TypeScript
interface Price {
currency?: string; // attribute
$value: string; // text content (decimal mapped to string by default)
}
`$3
Prevents precision loss and parsing errors at the cost of convenience:
| XSD Type | Default | Override Options | When to Override |
|---------------|----------|--------------------|----------------------------------------|
|
xs:long | string | number, bigint | Use number if values fit JS range |
| xs:integer | string | number | Use string for arbitrary-size ints |
| xs:decimal | string | number | Use string for precise decimals |
| xs:dateTime | string | Date | Use Date if runtime parsing is okay |Override with flags:
-
--client-int64-as number
- --client-decimal-as string
- --client-date-as Date$3
All output is stable and diff-friendly for CI/CD:
- ✅ Sorted type declarations
- ✅ Sorted OpenAPI paths, schemas, parameters
- ✅ Sorted JSON schema keys
- ✅ Stable alias resolution
- ✅ Consistent ordering of imports
Regenerate safely without spurious diffs in version control.
$3
catalog.json is the compiled representation of your WSDL:- Debuggable — Inspect types, operations, and metadata as JSON
- Cacheable — Reuse across client/OpenAPI/gateway generation
- Co-located — Automatically placed alongside generated output
Common locations:
-
client command: {client-dir}/catalog.json
- openapi command: {openapi-dir}/catalog.json
- pipeline command: First available output directory---
Common Workflows
$3
| I Want... | Use Command | Example |
|-----------------------------------------------|--------------|----------------------------------------------------------------------------------------------------------------------|
| Everything (client + OpenAPI + gateway) |
pipeline | npx wsdl-tsc pipeline --wsdl-source service.wsdl --client-dir ./client --openapi-file ./api.json --gateway-dir ./gateway --gateway-service-name svc --gateway-version-prefix v1 |
| Only a TypeScript SOAP client | client | npx wsdl-tsc client --wsdl-source service.wsdl --client-dir ./client |
| Only OpenAPI spec (for docs or SDKs) | openapi | npx wsdl-tsc openapi --wsdl-source service.wsdl --openapi-file ./api.json |
| Only REST gateway (have OpenAPI already) | gateway | npx wsdl-tsc gateway --openapi-file ./api.json --client-dir ./client --gateway-dir ./gateway --gateway-service-name svc --gateway-version-prefix v1 |
| Runnable server for testing | app | npx wsdl-tsc app --client-dir ./client --gateway-dir ./gateway --openapi-file ./api.json |
| Debug/inspect WSDL compilation | compile | npx wsdl-tsc compile --wsdl-source service.wsdl --catalog-file ./catalog.json |$3
Use
pipeline for complete stack generation:`bash
npx wsdl-tsc pipeline \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir ./src/services/weather \
--openapi-file ./docs/weather-api.json \
--gateway-dir ./src/gateway/weather \
--gateway-service-name weather \
--gateway-version-prefix v1
`Output:
- Client:
./src/services/weather/client.ts, types.ts, utils.ts, catalog.json
- OpenAPI: ./docs/weather-api.json
- Gateway: ./src/gateway/weather/ (routes, schemas, plugin)$3
Generate TypeScript client for direct SOAP integration:
`bash
npx wsdl-tsc client \
--wsdl-source ./wsdl/Hotel.wsdl \
--client-dir ./src/services/hotel
`Usage:
`typescript
import soap from 'soap';
import { Hotel } from './src/services/hotel/client.js';const client = new Hotel({
source: 'https://example.com/hotel.wsdl',
security: new soap.WSSecurity('username', 'password'),
});
const result = await client.SearchAvailableRooms({
checkIn: '2024-01-15',
checkOut: '2024-01-20',
guests: 2,
});
`$3
Generate OpenAPI spec for API documentation or SDK generation:
`bash
npx wsdl-tsc openapi \
--wsdl-source ./wsdl/Booking.wsdl \
--openapi-file ./docs/booking-api.yaml \
--openapi-format yaml \
--openapi-title "Hotel Booking API" \
--openapi-version "1.0.0" \
--openapi-servers https://api.example.com/v1
`Use the spec:
- Import into Postman, Insomnia, or Swagger UI
- Generate client SDKs with OpenAPI Generator
- Share as REST API documentation
$3
Build a REST API layer over legacy SOAP services:
`bash
1. Generate client + OpenAPI
npx wsdl-tsc pipeline \
--wsdl-source ./wsdl/Legacy.wsdl \
--client-dir ./src/services/legacy \
--openapi-file ./docs/legacy-api.json2. Generate gateway
npx wsdl-tsc gateway \
--openapi-file ./docs/legacy-api.json \
--client-dir ./src/services/legacy \
--gateway-dir ./src/gateway/legacy \
--gateway-service-name legacy \
--gateway-version-prefix v1
`Or in one command:
`bash
npx wsdl-tsc pipeline \
--wsdl-source ./wsdl/Legacy.wsdl \
--client-dir ./src/services/legacy \
--openapi-file ./docs/legacy-api.json \
--gateway-dir ./src/gateway/legacy \
--gateway-service-name legacy \
--gateway-version-prefix v1
`$3
Cache compiled catalog for faster multi-stage builds:
`bash
Stage 1: Compile catalog (cacheable)
npx wsdl-tsc compile \
--wsdl-source ./wsdl/Service.wsdl \
--catalog-file ./build/service-catalog.jsonStage 2: Generate client from catalog
npx wsdl-tsc client \
--catalog-file ./build/service-catalog.json \
--client-dir ./src/services/serviceStage 3: Generate OpenAPI from catalog
npx wsdl-tsc openapi \
--catalog-file ./build/service-catalog.json \
--openapi-file ./docs/service-api.json
`$3
Inspect compiled types and operations:
`bash
Compile to catalog
npx wsdl-tsc compile \
--wsdl-source ./wsdl/Complex.wsdl \
--catalog-file ./debug/catalog.jsonInspect types
cat ./debug/catalog.json | jq '.types'Inspect operations
cat ./debug/catalog.json | jq '.operations'
`---
Command Reference
The tool provides six commands for different integration scenarios. Commands are listed in recommended order of use:
| Command | Purpose | Typical Use Case |
|------------|----------------------------------------------------------------|-----------------------------------------------|
|
pipeline | Run full pipeline: client + OpenAPI + gateway (+ app optional) | CI/CD automation, complete stack generation (recommended) |
| client | Generate TypeScript SOAP client from WSDL or catalog | Standard SOAP integration |
| openapi | Generate OpenAPI 3.1 spec from WSDL or catalog | Documentation, REST proxies, API gateways |
| gateway | Generate Fastify gateway with full handlers from OpenAPI spec | Production REST gateway with SOAP integration |
| app | Generate runnable Fastify app from client + gateway + OpenAPI | Local testing, quick iteration, demos |
| compile | Parse WSDL and emit catalog.json only | Debugging, inspection, or multi-stage builds (advanced) |---
$3
Purpose: Run the complete generation pipeline in a single pass: WSDL parsing → TypeScript client → OpenAPI spec → Fastify gateway (+ app optional).
When to use:
- CI/CD automation
- Complete stack generation
- Ensuring all artifacts are generated from the same WSDL parse
- One-command development workflows
#### Usage
`bash
npx wsdl-tsc pipeline \
--wsdl-source \
[--catalog-file ] \
[--client-dir ] \
[--openapi-file ] \
[--gateway-dir ] \
[options]
`#### Required Flags
| Flag | Description |
|---------------------|----------------------------------------------------------------------|
|
--wsdl-source | Path or URL to WSDL file |#### Output Flags
| Flag | Default | Description |
|---------------------|---------------------------------------------|---------------------------------------------------|
|
--catalog-file | Co-located with first output (see below) | Output path for catalog.json (always generated) |Catalog Default Location: The catalog is automatically placed alongside the first available output:
- With
--client-dir: {client-dir}/catalog.json
- With --openapi-file only: {openapi-file-dir}/catalog.json
- With --gateway-dir only: {gateway-dir}/catalog.jsonNote: At least one of
--client-dir, --openapi-file, or --gateway-dir must be provided.#### Generation Control Flags
| Flag | Description |
|-------------------------|------------------------------------------------|
|
--client-dir | Generate TypeScript client in this directory |
| --openapi-file | Generate OpenAPI spec at this path |
| --gateway-dir | Generate Fastify gateway in this directory |
| --generate-app | Generate runnable app (requires gateway) |#### Optional Flags
All flags from
client, openapi, and gateway commands are supported. Key flags:Client Flags:
-
--import-extensions (default: js)
- --client-attributes-key (default: $attributes)
- --client-class-name
- --client-int64-as (default: string)
- --client-bigint-as (default: string)
- --client-decimal-as (default: string)
- --client-date-as (default: string)
- --client-choice-mode (default: all-optional)
- --client-fail-on-unresolved (default: false)
- --client-nillable-as-optional (default: false)OpenAPI Flags:
-
--openapi-format (default: json)
- --openapi-title
- --openapi-version (default: 0.0.0)
- --openapi-description
- --openapi-servers (default: /)
- --openapi-base-path
- --openapi-path-style (default: kebab)
- --openapi-method (default: post)
- --openapi-tag-style (default: default)
- --openapi-closed-schemas (default: false)
- --openapi-prune-unused-schemas (default: false)
- --openapi-envelope-namespace (default: ResponseEnvelope)
- --openapi-error-namespace (default: ErrorObject)
- --openapi-validate (default: true)
- --openapi-security-config-file
- --openapi-tags-file
- --openapi-ops-fileGateway Flags:
-
--gateway-service-name (required if --gateway-dir provided)
- --gateway-version-prefix (required if --gateway-dir provided)
- --gateway-default-status-codes
- --gateway-stub-handlers (default: false)#### Examples
Complete Stack Generation:
`bash
npx wsdl-tsc pipeline \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir tmp/client \
--openapi-file tmp/openapi.json \
--gateway-dir tmp/gateway \
--gateway-service-name weather \
--gateway-version-prefix v1
`With App Generation:
`bash
npx wsdl-tsc pipeline \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir tmp/client \
--openapi-file tmp/openapi.json \
--gateway-dir tmp/gateway \
--gateway-service-name weather \
--gateway-version-prefix v1 \
--generate-app
`Client + OpenAPI Only:
`bash
npx wsdl-tsc pipeline \
--wsdl-source https://example.com/Hotel.wsdl \
--client-dir ./build/client \
--openapi-file ./docs/hotel-api.json \
--openapi-format both
`With Full Configuration:
`bash
npx wsdl-tsc pipeline \
--wsdl-source ./wsdl/Booking.wsdl \
--client-dir ./build/client \
--openapi-file ./docs/booking-api \
--gateway-dir ./build/gateway \
--openapi-format both \
--openapi-servers https://api.example.com/v1 \
--openapi-base-path /booking \
--openapi-security-config-file ./config/security.json \
--gateway-service-name booking \
--gateway-version-prefix v1 \
--client-int64-as number \
--client-decimal-as string
`#### Pipeline Workflow
The pipeline command executes these steps in order:
1. Parse WSDL → Load and validate WSDL document
2. Compile Catalog → Generate intermediate representation
3. Emit Catalog → Write
catalog.json (always)
4. Generate Client → Emit TypeScript client files (if --client-dir)
5. Generate OpenAPI → Create OpenAPI spec (if --openapi-file)
6. Generate Gateway → Create Fastify gateway code (if --gateway-dir)
7. Generate App → Create runnable application (if --generate-app)All steps share the same parsed WSDL and compiled catalog, ensuring consistency.
---
$3
Purpose: Generate strongly-typed TypeScript SOAP client code from WSDL or a pre-compiled catalog.
When to use:
- Standard SOAP integration (most common use case)
- When you need TypeScript types and client methods for SOAP operations
- When building applications that consume SOAP services
$3
`bash
npx wsdl-tsc client --wsdl-source --client-dir [options]
OR
npx wsdl-tsc client --catalog-file --client-dir [options]
`$3
| Flag | Description |
|------------------|-------------------------------------------------|
|
--wsdl-source | Path or URL to WSDL file (see note below) |
| --client-dir | Output directory for generated TypeScript files |$3
| Flag | Default | Description |
|------------------|-----------------------------|----------------------------------------------------------------------|
|
--catalog-file | {client-dir}/catalog.json | Path to pre-compiled catalog.json (when not using --wsdl-source) |Note: Provide either
--wsdl-source (to compile from WSDL) or --catalog-file (to use pre-compiled catalog). When using --wsdl-source, the catalog is automatically generated in the client directory unless you override with --catalog-file.$3
| File | Purpose |
|----------------|------------------------------------------------------------------------------|
|
client.ts | Strongly-typed SOAP client wrapper with one method per operation |
| types.ts | Flattened TypeScript interfaces, type aliases, and enums |
| utils.ts | Runtime metadata for JSON to SOAP conversion (attribute mapping, occurrence) |
| catalog.json | (When using --wsdl-source) Generated in client directory by default |$3
All flags from
compile command, plus:| Flag | Default | Description |
|---------------------------------|----------------|-------------------------------------|
|
--import-extensions | js | Import style: js, ts, or bare |
| --client-attributes-key | $attributes | Attribute bag key |
| --client-class-name | (derived) | Override client class name |
| --client-int64-as | string | Map 64-bit integers |
| --client-bigint-as | string | Map arbitrary-size integers |
| --client-decimal-as | string | Map xs:decimal |
| --client-date-as | string | Map date/time types |
| --client-choice-mode | all-optional | Choice element strategy |
| --client-fail-on-unresolved | false | Fail on unresolved references |
| --client-nillable-as-optional | false | Treat nillable as optional |$3
#### Basic Generation (Default Catalog Location)
`bash
npx wsdl-tsc client \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir tmp/client
`Output: Generates client files and catalog at
tmp/client/catalog.json.#### With Custom Catalog Path
`bash
npx wsdl-tsc client \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir tmp/client \
--catalog-file build/shared-catalog.json
`#### With Custom Numeric Mappings
`bash
npx wsdl-tsc client \
--wsdl-source https://example.com/Hotel.wsdl \
--client-dir ./src/integrations/soap/hotel \
--client-int64-as number \
--client-decimal-as string \
--client-date-as string
`Output: Catalog generated at
./src/integrations/soap/hotel/catalog.json.#### From Pre-compiled Catalog
`bash
First compile the catalog
npx wsdl-tsc compile --wsdl-source https://example.com/Hotel.wsdl --catalog-file build/hotel-catalog.jsonThen generate client from catalog
npx wsdl-tsc client \
--catalog-file build/hotel-catalog.json \
--client-dir ./src/services/hotel
`$3
- Attributes & elements become peer properties (flattened)
- Text content becomes
$value property
- Required attributes: use!="optional"; elements minOccurs>=1
- Multiplicity: maxOccurs>1 or unbounded become arrays
- Nillable: nillable="true" preserved (optionally model as optional with --client-nillable-as-optional)
- Inheritance: extensions merged or emitted as extends; simpleContent base collapsed logically---
$3
Purpose: Generate OpenAPI 3.1 specification from WSDL or a pre-compiled catalog, mirroring the exact TypeScript type structure.
When to use:
- Creating REST API documentation for SOAP services
- Building API gateways or proxies
- Enabling REST-style access to SOAP operations
- Generating client SDKs in other languages
$3
`bash
npx wsdl-tsc openapi --wsdl-source --openapi-file [options]
OR
npx wsdl-tsc openapi --catalog-file --openapi-file [options]
`$3
| Flag | Description |
|---------------------|----------------------------------------------------|
|
--openapi-file | Output path for OpenAPI specification |$3
| Flag | Default | Description |
|---------------------|--------------------------------------|----------------------------------------------------|
|
--wsdl-source | (none) | Path or URL to WSDL file |
| --catalog-file | {openapi-file-dir}/catalog.json | Path to pre-compiled catalog.json |Note: Provide either
--wsdl-source or --catalog-file. When neither is provided, defaults to reading from the OpenAPI output directory. When using --wsdl-source, the catalog is automatically written to the OpenAPI output directory unless overridden.$3
| Flag | Default | Description |
|-------------------------------|-----------|----------------------------------------------------------|
|
--openapi-format | json | Output format: json, yaml, or both |
| --openapi-title | (derived) | API title in info section |
| --openapi-version | 0.0.0 | API version in info.version |
| --openapi-description | (empty) | API description in info section |
| --openapi-servers | / | Comma-separated server URLs |
| --openapi-base-path | (empty) | Base path prefix (e.g., /v1/soap) |
| --openapi-validate | true | Validate spec with swagger-parser |$3
| Flag | Default | Description |
|----------------------------------|-----------|--------------------------------------------------|
|
--openapi-path-style | kebab | Path transformation: kebab, asis, or lower |
| --openapi-method | post | Default HTTP method for operations |
| --openapi-tag-style | default | Tag inference: default, service, or first |
| --openapi-closed-schemas | false | Add additionalProperties: false to all schemas |
| --openapi-prune-unused-schemas | false | Emit only schemas referenced by operations |$3
| Flag | Default | Description |
|--------------------------------|--------------------|---------------------------------------------|
|
--openapi-envelope-namespace | ResponseEnvelope | Override envelope component name suffix |
| --openapi-error-namespace | ErrorObject | Override error object component name suffix |$3
| Flag | Description |
|-----------------------------------|-------------------------------------------------------|
|
--openapi-security-config-file | Path to security.json (schemes, headers, overrides) |
| --openapi-tags-file | Path to tags.json (explicit operation → tag map) |
| --openapi-ops-file | Path to ops.json (per-operation overrides) |$3
#### Basic JSON Output
`bash
npx wsdl-tsc openapi \
--wsdl-source examples/minimal/weather.wsdl \
--openapi-file ./docs/weather-api.json
`#### Multi-Format with Validation
`bash
npx wsdl-tsc openapi \
--wsdl-source https://example.com/Hotel.wsdl \
--openapi-file ./docs/hotel-api \
--openapi-format both \
--openapi-servers https://api.example.com/v1,https://api-staging.example.com/v1 \
--openapi-base-path /soap
`#### From Pre-compiled Catalog
`bash
npx wsdl-tsc openapi \
--catalog-file ./artifacts/hotel-catalog.json \
--openapi-file ./docs/hotel-api.json \
--openapi-format json
`#### With Custom Configuration
`bash
npx wsdl-tsc openapi \
--wsdl-source ./wsdl/Booking.wsdl \
--openapi-file ./docs/booking-api.yaml \
--openapi-format yaml \
--openapi-title "Hotel Booking API" \
--openapi-version "1.2.0" \
--openapi-description "REST API for hotel booking SOAP service" \
--openapi-security-config-file ./config/security.json \
--openapi-tags-file ./config/tags.json \
--openapi-path-style kebab \
--openapi-method post \
--openapi-tag-style service
`$3
All responses are wrapped in a standard envelope for consistency and debuggability (always-on since 0.7.1):
#### Base Envelope Structure
`typescript
{
status: string; // e.g., "SUCCESS", "FAILURE", "PENDING"
message: string | null; // diagnostic message (not for end-user UI)
data: T | null; // operation payload (typed per operation)
error: ErrorObject | null; // populated on failures
}
`#### Error Object Structure
`typescript
{
code: string; // stable machine error code
message: string; // brief description
details: object | null; // arbitrary extra info
}
`#### Naming Rules
- Base envelope:
${serviceName}ResponseEnvelope (override with --openapi-envelope-namespace)
- Error object: ${serviceName}ErrorObject (override with --openapi-error-namespace)
- Per-operation extension: (refines data field)#### Collision Avoidance
If the payload type already ends with the namespace prefix, an underscore is inserted:
- Payload
WeatherResponse + default ResponseEnvelope → WeatherResponse_ResponseEnvelope
- Payload Booking + default ResponseEnvelope → BookingResponseEnvelope#### Example
`bash
npx wsdl-tsc openapi \
--wsdl-source ./wsdl/Hotel.wsdl \
--openapi-file ./docs/hotel-api.json \
--openapi-envelope-namespace ApiEnvelope \
--openapi-error-namespace ApiError
`Produces components:
1.
HotelApiEnvelope (base)
2. extension schemas (alphabetically sorted)
3. HotelApiError (error object)
4. Domain schemas$3
| Strategy | Behavior |
|-----------|------------------------------------------------------------------------------------|
|
default | Single tag = service name (fallback SOAP) |
| service | Always service name (even if operation prefix differs) |
| first | First lexical segment of CamelCase operation (e.g., GetCityWeatherByZIP → Get) |Use
--openapi-tags-file for explicit mapping when heuristics are insufficient.$3
All generated OpenAPI specs have deterministic ordering:
- Path keys (alphabetically sorted)
- HTTP methods within paths (alphabetically sorted)
- Component schema names (alphabetically sorted)
- Security schemes (alphabetically sorted)
- Parameters (alphabetically sorted)
- Operation tag arrays (alphabetically sorted)
This ensures diff-friendly output for version control.
---
$3
Purpose: Generate a production-ready Fastify gateway with fully functional route handlers from an OpenAPI 3.1 specification. This creates a complete REST API layer over your SOAP client with automatic request/response transformation and standardized envelope responses.
When to use:
- Building a REST API gateway for legacy SOAP services
- Creating a modern HTTP/JSON interface for SOAP operations
- Setting up request/response validation with JSON Schema
- Establishing Fastify routing structure with full handler implementations
What it generates:
- Fastify route registration files with complete handler implementations
- JSON Schema models with URN-based IDs
- Operation schemas (request/response validation)
- Schema and route registration modules
- Runtime utilities (envelope builders, error handlers)
- Fastify plugin wrapper for simplified integration
$3
`bash
npx wsdl-tsc gateway \
--openapi-file \
--client-dir \
--gateway-dir \
--gateway-service-name \
--gateway-version-prefix \
[options]
`$3
| Flag | Description |
|----------------------------|--------------------------------------------------------------------------|
|
--openapi-file | Path to OpenAPI 3.1 JSON or YAML file |
| --client-dir | Path to client directory (where client.ts is located) |
| --gateway-dir | Output directory for generated gateway code |
| --gateway-service-name | Service identifier for URN generation (e.g., weather, booking) |
| --gateway-version-prefix | Version prefix for URN generation (e.g., v1, v2, urn:1.0.2:schema) |$3
| Flag | Default | Description |
|----------------------------------|---------------------------------------------------|-------------------------------------------------------------|
|
--import-extensions | js | Import style: js, ts, or bare |
| --gateway-default-status-codes | 200,400,401,403,404,409,422,429,500,502,503,504 | Comma-separated status codes to backfill |
| --catalog-file | (none) | Path to catalog.json for operation metadata |
| --gateway-client-class-name | (auto-detected) | Override SOAP client class name |
| --gateway-decorator-name | {serviceSlug}Client | Fastify decorator name for client instance |
| --gateway-stub-handlers | false | Generate stub handlers instead of full implementations |
| --gateway-skip-plugin | false | Skip generating plugin.ts wrapper |
| --gateway-skip-runtime | false | Skip generating runtime.ts utilities |> Note: Route URLs are derived from the OpenAPI document paths, which already include any base path configured during OpenAPI generation (via
--openapi-base-path). There is no separate route prefix option for the gateway.$3
`
{gateway-dir}/
├── schemas/
│ ├── models/ # JSON Schema components with URN IDs
│ │ ├── .json
│ │ ├── .json
│ │ └── ...
│ └── operations/ # Fastify operation schemas
│ ├── .json
│ ├── .json
│ └── ...
├── routes/ # Route registration files with full handlers
│ ├── .ts
│ ├── .ts
│ └── ...
├── schemas.ts # Schema registration module
├── routes.ts # Route aggregator module
├── runtime.ts # Envelope builders and error handler
└── plugin.ts # Fastify plugin wrapper (recommended entry point)
`$3
All generated JSON Schemas use deterministic URN identifiers:
`
urn:services:{serviceSlug}:{versionSlug}:schemas:{models|operations}:{schemaSlug}
`Example:
urn:services:weather:v1:schemas:models:getcityweatherbyzipresponse$3
The gateway generator enforces strict OpenAPI contract validation:
- All request/response bodies must use
$ref to components.schemas (no inline schemas)
- Every operation must have a default response with application/json content
- All schemas referenced by operations must exist in components.schemas$3
#### Basic Gateway Generation
`bash
npx wsdl-tsc gateway \
--openapi-file ./docs/weather-api.json \
--client-dir ./src/services/weather \
--gateway-dir ./src/gateway/weather \
--gateway-service-name weather \
--gateway-version-prefix v1
`#### With Custom Status Codes
`bash
npx wsdl-tsc gateway \
--openapi-file ./docs/hotel-api.json \
--client-dir ./src/services/hotel \
--gateway-dir ./src/gateway/hotel \
--gateway-service-name hotel \
--gateway-version-prefix v2 \
--gateway-default-status-codes 200,400,401,404,500
`#### From YAML OpenAPI
`bash
npx wsdl-tsc gateway \
--openapi-file ./docs/booking-api.yaml \
--client-dir ./src/services/booking \
--gateway-dir ./src/gateway/booking \
--gateway-service-name booking \
--gateway-version-prefix v1
`$3
The generated gateway provides a Fastify plugin for simplified integration.
#### Prerequisites
Your host application needs these dependencies:
`bash
npm install fastify fastify-plugin
`#### Using the Generated Plugin (Recommended)
`typescript
import Fastify from 'fastify';
import weatherGateway from './gateway/plugin.js';
import { Weather } from './client/client.js';const app = Fastify({ logger: true });
// Create and configure SOAP client
const weatherClient = new Weather({
source: 'https://example.com/weather.wsdl',
// security: new soap.WSSecurity('user', 'pass'), // if needed
});
// Register gateway plugin with client
await app.register(weatherGateway, {
client: weatherClient,
// Note: Route paths are determined by --openapi-base-path during generation.
// The prefix option here adds an ADDITIONAL runtime prefix on top of generated paths.
// Only use if you need to mount routes under a different sub-path at runtime.
});
await app.listen({ port: 3000 });
`The plugin automatically:
- Decorates Fastify with the SOAP client (
fastify.weatherClient)
- Registers all JSON schemas for validation
- Installs a centralized error handler
- Registers all routes with full handler implementations#### Using Individual Components (Advanced)
For more control, you can use the individual modules:
`typescript
import Fastify from 'fastify';
import { registerSchemas_v1_weather } from './gateway/schemas.js';
import { registerRoutes_v1_weather } from './gateway/routes.js';
import { createGatewayErrorHandler_v1_weather } from './gateway/runtime.js';
import { Weather } from './client/client.js';const app = Fastify({ logger: true });
// Manual setup
const weatherClient = new Weather({ source: 'weather.wsdl' });
app.decorate('weatherClient', weatherClient);
// Register schemas
await registerSchemas_v1_weather(app);
// Install error handler
app.setErrorHandler(createGatewayErrorHandler_v1_weather());
// Register routes (paths already include --openapi-base-path if configured)
await registerRoutes_v1_weather(app);
await app.listen({ port: 3000 });
`$3
Route handlers are fully implemented and call the SOAP client automatically:
`typescript
// Generated: routes/get-city-forecast-by-zip.ts
import type { FastifyInstance } from "fastify";
import schema from "../schemas/operations/getcityforecastbyzip.json" with { type: "json" };
import { buildSuccessEnvelope } from "../runtime.js";export async function registerRoute_v1_weather_getcityforecastbyzip(fastify: FastifyInstance) {
fastify.route({
method: "POST",
url: "/get-city-forecast-by-zip",
schema,
handler: async (request) => {
const client = fastify.weatherClient;
const result = await client.GetCityForecastByZIP(request.body);
return buildSuccessEnvelope(result.response);
},
});
}
`$3
All responses are wrapped in a standard envelope format:
Success Response:
`
{
"status": "SUCCESS",
"message": null,
"data": { / SOAP response data / },
"error": null
}
`Error Response:
`
{
"status": "ERROR",
"message": "Request validation failed",
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": { / validation errors / }
}
}
`$3
The centralized error handler (
runtime.ts) automatically classifies errors:| Error Type | HTTP Status | Error Code |
|-----------------------|-------------|-----------------------|
| Validation errors | 400 |
VALIDATION_ERROR |
| SOAP faults | 502 | SOAP_FAULT |
| Connection refused | 503 | SERVICE_UNAVAILABLE |
| Timeout | 504 | GATEWAY_TIMEOUT |
| Other errors | 500 | INTERNAL_ERROR |$3
If you prefer to implement handler logic manually or need custom transformation logic beyond the standard SOAP-to-REST mapping, use stub mode:
`bash
npx wsdl-tsc gateway \
--openapi-file ./docs/weather-api.json \
--client-dir ./src/services/weather \
--gateway-dir ./src/gateway/weather \
--gateway-service-name weather \
--gateway-version-prefix v1 \
--gateway-stub-handlers
`This generates minimal handler stubs that throw "Not implemented" errors, allowing you to implement fully custom logic while keeping the routing and validation infrastructure.
---
$3
Purpose: Generate a runnable Fastify application that integrates the generated client, gateway, and OpenAPI spec. This provides an immediately executable server for testing, development, and demonstrations.
When to use:
- Local testing and development
- Quick iteration on gateway configurations
- Demonstrating the generated API
- CI smoke testing
$3
`bash
npx wsdl-tsc app \
--client-dir \
--gateway-dir \
--openapi-file \
[--catalog-file ] \
[--app-dir ] \
[options]
`$3
| Flag | Description |
|------------------|----------------------------------------------------------|
|
--client-dir | Path to client directory (where client.ts is located) |
| --gateway-dir | Path to gateway directory (where plugin.ts is located) |
| --openapi-file | Path to OpenAPI specification file |$3
| Flag | Default | Description |
|-----------------------|-------------------------------|---------------------------------------------------|
|
--catalog-file | {client-dir}/catalog.json | Path to catalog.json (for metadata extraction) |
| --app-dir | {gateway-dir}/../app | Output directory for generated app |
| --import-extensions | Inferred from catalog or js | Import-extension mode: js, ts, or bare |
| --host | 127.0.0.1 | Default server host |
| --port | 3000 | Default server port |
| --prefix | "" (empty) | Route prefix |
| --logger | true | Enable Fastify logger |
| --openapi-mode | copy | How to handle OpenAPI file: copy or reference |$3
#### Generate App After Pipeline
`bash
First generate client, OpenAPI, and gateway
npx wsdl-tsc pipeline \
--wsdl-source weather.wsdl \
--client-dir ./client \
--openapi-file ./openapi.json \
--gateway-dir ./gateway \
--gateway-service-name weather \
--gateway-version-prefix v1Then generate runnable app
npx wsdl-tsc app \
--client-dir ./client \
--gateway-dir ./gateway \
--openapi-file ./openapi.json \
--app-dir ./app
`#### Generate App with Custom Configuration
`bash
npx wsdl-tsc app \
--client-dir ./client \
--gateway-dir ./gateway \
--openapi-file ./openapi.json \
--app-dir ./my-app \
--host 0.0.0.0 \
--port 8080 \
--prefix /api/v1
`$3
The
app command generates the following files:`
app/
├── server.js (or .ts) # Main application entry point
├── config.js (or .ts) # Configuration loader with env support
├── .env.example # Environment variable template
├── README.md # Usage instructions
└── openapi.json # OpenAPI spec (when --openapi-mode=copy)
`$3
`bash
Copy environment template
cd app
cp .env.example .envEdit .env to configure WSDL source and other settings
vim .env
Run the server
npx tsx server.js # For TypeScript files
or
node server.js # For JavaScript files
`$3
The generated app loads configuration from environment variables with the following precedence:
1. Environment variables (runtime overrides)
2. Catalog defaults (from generation-time)
3. Hard defaults (in config file)
#### Environment Variables
| Variable | Default (from catalog or flags) | Description |
|-----------------|---------------------------------|--------------------------------------|
|
WSDL_SOURCE | From catalog or required | WSDL URL or local file path |
| HOST | 127.0.0.1 | Server bind address |
| PORT | 3000 | Server listen port |
| PREFIX | "" (empty) | Route prefix |
| LOGGER | true | Enable Fastify logger |$3
The generated app serves the following endpoints:
#### Health Check
`bash
GET /health
`
Returns: { "ok": true }#### OpenAPI Specification
`bash
GET /openapi.json
`
Returns: Complete OpenAPI 3.1 specification#### Gateway Routes
All SOAP operations are exposed as REST endpoints. See the OpenAPI spec for complete API documentation.
$3
`bash
Start the server
cd app
npx tsx server.jsTest health endpoint
curl http://localhost:3000/healthGet OpenAPI spec
curl http://localhost:3000/openapi.json | jq .Call a gateway operation (example)
curl -X POST http://localhost:3000/get-weather-information \
-H "Content-Type: application/json" \
-d '{}'
`$3
The
app command can also be used via the pipeline with the --generate-app flag:`bash
npx wsdl-tsc pipeline \
--wsdl-source weather.wsdl \
--client-dir ./client \
--openapi-file ./openapi.json \
--gateway-dir ./gateway \
--gateway-service-name weather \
--gateway-version-prefix v1 \
--generate-app
`This generates all artifacts including the runnable app in a single command.
---
$3
Purpose: Parse WSDL and generate only the intermediate
catalog.json representation without TypeScript client code.When to use:
- Multi-stage builds where you want to cache the parsed WSDL
- Debugging or inspecting the compiled schema structure
- Sharing a compiled catalog across multiple generation targets
#### Usage
`bash
npx wsdl-tsc compile --wsdl-source --catalog-file [options]
`#### Required Flags
| Flag | Description |
|---------------------|------------------------------------------|
|
--wsdl-source | Path or URL to the WSDL file |
| --catalog-file | Output path for catalog.json |#### Optional Flags
| Flag | Default | Description |
|------------------------------------|----------------|--------------------------------------------------------------|
|
--import-extensions | js | Import specifier style: js, ts, or bare |
| --client-attributes-key | $attributes | Attribute bag key for runtime mapper |
| --client-class-name | (derived) | Override generated client class name |
| --client-int64-as | string | Map 64-bit integers: string, number, or bigint |
| --client-bigint-as | string | Map arbitrary-size integers: string or number |
| --client-decimal-as | string | Map xs:decimal: string or number |
| --client-date-as | string | Map date/time types: string or Date |
| --client-choice-mode | all-optional | Choice element strategy: all-optional or union |
| --client-fail-on-unresolved | false | Fail build on unresolved type references |
| --client-nillable-as-optional | false | Treat nillable elements as optional properties |#### Examples
Basic Compilation:
`bash
npx wsdl-tsc compile \
--wsdl-source examples/minimal/weather.wsdl \
--catalog-file tmp/catalog.json
`With Custom Mapping Options:
`bash
npx wsdl-tsc compile \
--wsdl-source https://example.com/Hotel.wsdl \
--catalog-file ./build/hotel-catalog.json \
--client-int64-as number \
--client-decimal-as string
`For Debugging:
`bash
Compile to inspect types and operations
npx wsdl-tsc compile \
--wsdl-source ./wsdl/ComplexService.wsdl \
--catalog-file ./debug/catalog.json \
--client-fail-on-unresolved falseInspect types
cat ./debug/catalog.json | jq '.types'Inspect operations
cat ./debug/catalog.json | jq '.operations'
`#### Output
-
catalog.json - Compiled schema representation including types, operations, and metadata#### Catalog Structure
The catalog.json file contains the compiled WSDL representation:
`json
{
"wsdlUri": "path/to/service.wsdl",
"targetNamespace": "http://example.com/service",
"serviceName": "WeatherService",
"types": [
{
"name": "GetWeatherRequest",
"properties": []
}
],
"operations": [
{
"name": "GetWeather",
"input": "GetWeatherRequest",
"output": "GetWeatherResponse"
}
],
"options": {
"imports": "js",
"catalog": true
}
}
`Key sections:
-
types - All compiled type definitions with properties and inheritance
- operations - SOAP operations with input/output type references
- options - Compiler options used during generationThis catalog can be reused with the
client and openapi commands via --catalog-file.#### Catalog Co-location
Default behavior: Catalog files are co-located with their primary output files for better organization and discoverability.
Catalog Location by Command:
-
compile: Always requires explicit --catalog-file (no default)
- client: Defaults to {client-dir}/catalog.json
- openapi: Defaults to {openapi-file-dir}/catalog.json
- pipeline: Intelligent cascade - first available: {client-dir} > {openapi-dir} > {gateway-dir} > tmp/Common patterns:
1. Co-located with client (recommended for most projects):
`bash
npx wsdl-tsc client --wsdl-source service.wsdl --client-dir src/services/weather
`
Creates src/services/weather/catalog.json automatically.2. Shared catalog for multiple commands (custom location):
`bash
npx wsdl-tsc compile --wsdl-source service.wsdl --catalog-file build/shared-catalog.json
npx wsdl-tsc client --catalog-file build/shared-catalog.json --client-dir src/client
npx wsdl-tsc openapi --catalog-file build/shared-catalog.json --openapi-file docs/api.json
`---
Working With Generated Clients
$3
`typescript
import soap from "soap";
import { Weather } from "./src/services/weather/client.js";const client = new Weather({
source: "https://example.com/WeatherService?wsdl",
security: new soap.WSSecurity("username", "password")
});
`$3
`typescript
// Operation with input
const forecast = await client.GetCityForecastByZIP({
ZIP: "10001"
});console.log(forecast.GetCityForecastByZIPResult.Success);
console.log(forecast.GetCityForecastByZIPResult.ForecastResult);
// Operation without input
const info = await client.GetWeatherInformation({});
console.log(info.GetWeatherInformationResult.WeatherDescriptions);
`$3
When an element has both attributes and text content, use the
$value convention:`typescript
const price = {
currencyCode: "USD", // attribute
$value: "123.45" // text content
};
`$3
Repeated elements are automatically typed as arrays:
`typescript
interface ForecastReturn {
Forecast: Forecast[]; // maxOccurs > 1
}
`$3
All operations and types are fully typed:
`typescript
// TypeScript knows the exact shape
const result: GetCityWeatherByZIPResponse = await client.GetCityWeatherByZIP({
ZIP: "10001"
});// Autocomplete and type checking work
result.GetCityWeatherByZIPResult.Temperature; // number | string (depends on mapping)
`---
Configuration Files
$3
Define security schemes, headers, and per-operation overrides:
`json
{
"global": {
"scheme": "bearer",
"bearer": { "bearerFormat": "JWT" },
"headers": [
{
"name": "X-Correlation-Id",
"required": false,
"schema": { "type": "string" }
}
]
},
"overrides": {
"CancelBooking": { "scheme": "apiKey" }
}
}
`Supported schemes:
none, basic, bearer, apiKey, oauth2$3
Explicit operation → tag mapping:
`json
{
"GetCityWeatherByZIP": ["Weather", "Forecast"],
"GetWeatherInformation": ["Weather", "Info"],
"CancelBooking": ["Booking", "Cancellation"]
}
`$3
Per-operation overrides for method, summary, description, and deprecation:
`json
{
"GetCityWeatherByZIP": {
"method": "get",
"summary": "Get weather forecast by ZIP code",
"description": "Returns a detailed weather forecast for the specified US ZIP code",
"deprecated": false
},
"LegacyOperation": {
"deprecated": true
}
}
`---
Production Concerns
$3
All generated code and specifications have stable, deterministic ordering for version control:
- ✅ TypeScript files: Sorted type declarations, imports, and exports
- ✅ OpenAPI specs: Sorted paths, HTTP methods, schemas, parameters, security schemes, tags
- ✅ JSON Schemas: Sorted property keys and component names
- ✅ Gateway routes: Alphabetically organized route files
- ✅ Catalog JSON: Consistent ordering of types and operations
Benefit: Safe regeneration in CI/CD without spurious diffs.
$3
OpenAPI Validation (enabled by default):
- Uses
@apidevtools/swagger-parser
- Validates schema structure
- Resolves all $ref references
- Catches missing schemas and circular dependencies
- Disable with --openapi-validate falseGateway Contract Validation:
- All request/response bodies must use
$ref to components.schemas
- Every operation must have a default response with application/json content
- All referenced schemas must exist in components.schemas$3
Gateway Error Classification:
| Error Type | HTTP Status | Error Code | When It Occurs |
|-----------------------|-------------|-----------------------|---------------------------------------|
| Validation errors | 400 |
VALIDATION_ERROR | Request doesn't match JSON Schema |
| SOAP faults | 502 | SOAP_FAULT | SOAP service returned a fault |
| Connection refused | 503 | SERVICE_UNAVAILABLE | Cannot reach SOAP endpoint |
| Timeout | 504 | GATEWAY_TIMEOUT | SOAP request exceeded timeout |
| Other errors | 500 | INTERNAL_ERROR | Unexpected errors |All errors are wrapped in the standard envelope format with
error object populated.$3
Enable SOAP request/response debugging:
`bash
NODE_DEBUG=soap node app.js
`This logs full XML request/response payloads to console.
$3
Caching Strategy:
`bash
Step 1: Compile catalog (cacheable artifact)
npx wsdl-tsc compile \
--wsdl-source ./wsdl/Service.wsdl \
--catalog-file ./build/catalog.jsonStep 2: Generate code from cached catalog
npx wsdl-tsc client --catalog-file ./build/catalog.json --client-dir ./src/client
npx wsdl-tsc openapi --catalog-file ./build/catalog.json --openapi-file ./docs/api.json
`Recommended Build Script (
package.json):`json
{
"scripts": {
"generate": "npx wsdl-tsc pipeline --wsdl-source ./wsdl/service.wsdl --client-dir ./src/client --openapi-file ./docs/api.json --gateway-dir ./src/gateway --gateway-service-name svc --gateway-version-prefix v1",
"build": "npm run generate && tsc",
"typecheck": "tsc --noEmit"
}
}
`$3
Choice Elements:
- Current strategy:
all-optional (all branches optional)
- Future: Discriminated union support (planned)Union Types:
- Experimental
--client-choice-mode union available
- May require manual refinement for complex patternsWS-Policy:
- Security hints extracted from policies
- Custom policies may require manual security configuration
Array Wrapper Flattening:
- Single-child sequences with
maxOccurs>1 become array schemas
- Sequences with multiple children preserve wrapper---
Programmatic API
All CLI commands are available as TypeScript functions for programmatic usage.
$3
Generate TypeScript SOAP client from WSDL.
`typescript
import { compileWsdlToProject } from "@techspokes/typescript-wsdl-client";await compileWsdlToProject({
wsdl: "./wsdl/Hotel.wsdl",
outDir: "./src/services/hotel",
options: {
imports: "js",
catalog: true,
primitive: {
int64As: "number",
bigIntegerAs: "string",
decimalAs: "string",
dateAs: "string"
},
choice: "all-optional",
clientName: "HotelClient",
nillableAsOptional: false
}
});
`Type Signature:
`typescript
// noinspection JSAnnotator
function compileWsdlToProject(input: {
wsdl: string;
outDir: string;
options?: Partial;
}): Promise;
`Options (
CompilerOptions):`typescript
interface CompilerOptions {
wsdl: string;
out: string;
imports: "js" | "ts" | "bare";
catalog: boolean;
primitive: PrimitiveOptions;
choice?: "all-optional" | "union";
failOnUnresolved?: boolean;
attributesKey?: string;
clientName?: string;
nillableAsOptional?: boolean;
}interface PrimitiveOptions {
int64As?: "string" | "number" | "bigint";
bigIntegerAs?: "string" | "number";
decimalAs?: "string" | "number";
dateAs?: "string" | "Date";
}
`$3
Generate OpenAPI 3.1 specification from WSDL or catalog.
`typescript
import { generateOpenAPI } from "@techspokes/typescript-wsdl-client";const { doc, jsonPath, yamlPath } = await generateOpenAPI({
wsdl: "./wsdl/Hotel.wsdl",
outFile: "./docs/hotel-api",
format: "both",
title: "Hotel Booking API",
version: "1.0.0",
servers: ["https://api.example.com/v1"],
basePath: "/booking",
pathStyle: "kebab",
tagStyle: "service",
validate: true
});
`Type Signature:
`typescript
// noinspection JSAnnotator
function generateOpenAPI(opts: GenerateOpenAPIOptions): Promise<{
doc: any;
jsonPath?: string;
yamlPath?: string;
}>;
`Options (
GenerateOpenAPIOptions):`typescript
interface GenerateOpenAPIOptions {
// Input sources (mutually exclusive)
wsdl?: string;
catalogFile?: string;
compiledCatalog?: CompiledCatalog;
// Output
outFile?: string;
format?: "json" | "yaml" | "both";
// Metadata
title?: string;
version?: string;
description?: string;
servers?: string[];
// Path configuration
basePath?: string;
pathStyle?: "kebab" | "asis" | "lower";
defaultMethod?: string;
// Schema configuration
closedSchemas?: boolean;
pruneUnusedSchemas?: boolean;
// Tag configuration
tagStyle?: "default" | "first" | "service";
tagsFile?: string;
// Security & operations
securityConfigFile?: string;
opsFile?: string;
// Envelope customization
envelopeNamespace?: string;
errorNamespace?: string;
// Validation
validate?: boolean;
skipValidate?: boolean;
// Deprecated
asYaml?: boolean;
}
`$3
Generate Fastify gateway code from OpenAPI specification.
`typescript
import { generateGateway } from "@techspokes/typescript-wsdl-client";await generateGateway({
openapiFile: "./docs/hotel-api.json",
outDir: "./src/gateway/hotel",
clientDir: "./src/services/hotel",
versionSlug: "v1",
serviceSlug: "hotel",
defaultResponseStatusCodes: [200, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504],
imports: "js"
});
`Type Signature:
`typescript
// noinspection JSAnnotator
function generateGateway(opts: GenerateGatewayOptions): Promise;
`Options (
GenerateGatewayOptions):`typescript
interface GenerateGatewayOptions {
// Input sources (mutually exclusive)
openapiFile?: string;
openapiDocument?: any;
// Output
outDir: string;
// Client integration
clientDir?: string;
// URN configuration
versionSlug?: string;
serviceSlug?: string;
// Schema configuration
defaultResponseStatusCodes?: number[];
// Import style
imports?: "js" | "ts" | "bare";
}
`$3
Run complete pipeline: client + OpenAPI + gateway in one pass.
`typescript
import { runGenerationPipeline } from "@techspokes/typescript-wsdl-client";const { compiled, openapiDoc } = await runGenerationPipeline({
wsdl: "./wsdl/Hotel.wsdl",
catalogOut: "./build/hotel-catalog.json",
clientOutDir: "./src/services/hotel",
compiler: {
imports: "js",
primitive: {
int64As: "number",
decimalAs: "string"
}
},
openapi: {
outFile: "./docs/hotel-api.json",
format: "both",
servers: ["https://api.example.com/v1"],
tagStyle: "service"
},
gateway: {
outDir: "./src/gateway/hotel",
versionSlug: "v1",
serviceSlug: "hotel"
}
});
`Type Signature:
`typescript
// noinspection JSAnnotator
function runGenerationPipeline(opts: PipelineOptions): Promise<{
compiled: CompiledCatalog;
openapiDoc?: any;
}>;
`Options (
PipelineOptions):``typescript