OpenAPI Client Generator

A repository providing a reusable GitHub Actions workflow for generating and publishing OpenAPI clients to npm.

Overview

This repository contains a reusable workflow that can be called from other repositories to generate TypeScript clients from OpenAPI specifications and publish them to npm.

Features

• Reusable Workflow: Call from any repository using workflow_call
• Hardcoded Generator Settings: Consistent client generation with standardized configuration
• OIDC Trusted Publishing: Secure, tokenless npm publishing with provenance attestation
• Dry-Run Mode: Test client generation without publishing

Usage

Calling the Reusable Workflow

Add the following workflow to your repository (e.g., .github/workflows/update-api-client.yml):

name: Update API Client Package

on:
  push:
    branches: [main]
    paths: ['api/openapi.yaml']
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to publish'
        required: true

# Required for npm Trusted Publishing (OIDC)
permissions:
  id-token: write
  contents: read

jobs:
  generate-client:
    uses: kubev2v/migration-planner-client-generator/.github/workflows/generate-and-publish.yml@main
    with:
      openapi-spec-url: "https://raw.githubusercontent.com/your-org/your-repo/main/api/openapi.yaml"
      package-name: "@your-scope/api-client"
      package-version: ${{ inputs.version || '0.0.1' }}
    # Required: passes OIDC permissions to the reusable workflow
    secrets: inherit

Workflow Inputs

Input	Required	Default	Description
openapi-spec-url	Yes	-	URL to the OpenAPI specification file
package-name	Yes	-	npm package name (e.g., @scope/package-name)
package-version	Yes	-	Package version to publish (semver)
npm-registry	No	https://registry.npmjs.org	npm registry URL
dry-run	No	false	Skip npm publish (for testing)

npm Publishing Authentication

This workflow uses npm Trusted Publishing (OIDC) exclusively — no long-lived tokens:

• No npm tokens needed — OIDC provides short-lived, workflow-specific credentials
• Requires id-token: write permission in calling workflow
• Requires Trusted Publisher configured on npmjs.com
• Use secrets: inherit to pass OIDC permissions to the reusable workflow
• Provenance attestation is automatically generated by npm Trusted Publishing

Generator Configuration

The workflow uses hardcoded generator settings that cannot be modified by callers:

Setting	Value
Generator	typescript-fetch
Output Directory	generated-client
ensureUniqueParams	true
supportsES6	true
withInterfaces	true
importFileExtension	.js

These settings match the configuration in kubev2v/migration-planner-ui.

Local Development

Testing with act-cli

Use act to test GitHub Actions locally:

# Install act (macOS)
brew install act

# Run test workflow (dry-run mode - no npm publishing)
make test

# Cleanup generated files
make clean

Note: OIDC Trusted Publishing does not work locally with act-cli. Local testing is limited to dry-run mode. To test actual npm publishing, use the CI feature toggle described below.

Make Targets

Command	Description
make test	Run workflow in dry-run mode via act (tests generation/build only)
make test-verbose	Run workflow with verbose output
make clean	Remove generated artifacts

CI Feature Toggle

The test workflow runs in dry-run mode by default to avoid npm rate limits.

To enable actual npm publishing in CI:

1. Go to Settings > Secrets and variables > Actions > Variables
2. Add: TEST_NPM_PUBLISH = true
3. Bump TEST_PACKAGE_VERSION in test.yml before each test

When enabled, test packages are automatically unpublished after successful publish.

Repository Structure

.
├── .github/
│   └── workflows/
│       ├── generate-and-publish.yml   # Reusable workflow
│       └── test.yml                   # CI test workflow
├── .actrc                             # act-cli configuration
├── .gitignore
├── Makefile                           # Local testing commands
├── AGENTS.md                          # AI agent guidelines
├── LICENSE                            # Apache-2.0
└── README.md                          # This file

Related

• ECOPROJECT-3956 - Jira issue for this project
• kubev2v/migration-planner-ui - UI monorepo using this workflow
• kubev2v/migration-planner - Backend API repository
• openapi-generator - OpenAPI Generator documentation

License

Apache-2.0