oapi-codegen generator & Go client publishing

  - Support oapi-codegen as default Go generator (creates cleaner single-file client)
  - Add bin/publish script to publish versioned Go clients to dedicated repository
  - Configure GitHub Actions workflow for automated publishing
  - Add operationId fields to CAPI endpoints for better SDK generation
  - Auto-generate go.mod with proper module paths and dependencies

Author: wayneeseguin

Makefile

@@ -1,4 +1,4 @@
-.PHONY: deps deps-openapi deps-spruce deps-jq deps-java help gen-go-client
+.PHONY: deps deps-openapi deps-oapi-codegen deps-spruce deps-jq deps-java help gen-go-client
 
 # Default target
 .DEFAULT_GOAL := help
@@ -12,7 +12,7 @@ CAPI_VERSION ?= 3.195.0
 help: ## Display this help screen
 	@grep -h -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
-deps: deps-java deps-openapi deps-spruce deps-jq ## Install all dependencies
+deps: deps-java deps-openapi deps-oapi-codegen deps-spruce deps-jq ## Install all dependencies
 
 deps-java: ## Install Java Runtime Environment
 	@echo "Checking/Installing Java..."
@@ -46,6 +46,14 @@ deps-openapi: deps-java ## Install OpenAPI Generator CLI
 	fi
 	bun install @openapitools/openapi-generator-cli -g
 
+deps-oapi-codegen: ## Install oapi-codegen for Go client generation
+	@echo "Installing oapi-codegen..."
+	@if ! command -v go &> /dev/null; then \
+		echo "Go is not installed. Please install Go first: https://golang.org/"; \
+		exit 1; \
+	fi
+	go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
+
 deps-spruce: ## Install Spruce
 	@echo "Installing Spruce..."
 	@if [ "$(UNAME_S)" = "Darwin" ]; then \
@@ -84,6 +92,7 @@ check-deps: ## Check if all dependencies are installed
 	@echo "Checking dependencies..."
 	@command -v spruce >/dev/null 2>&1 || { echo "spruce is not installed. Run 'make deps-spruce'"; exit 1; }
 	@command -v jq >/dev/null 2>&1 || { echo "jq is not installed. Run 'make deps-jq'"; exit 1; }
+	@command -v oapi-codegen >/dev/null 2>&1 || { echo "oapi-codegen is not installed. Run 'make deps-oapi-codegen'"; exit 1; }
 	@echo "All dependencies are installed!"
 
 prepare: check-deps ## Prepare the OpenAPI specification
@@ -94,7 +103,7 @@ gen-openapi-spec: check-deps ## Merge the CAPI OpenAPI specifications
 	@echo "Merging CAPI OpenAPI specifications..."
 	./bin/gen merge --version=$(CAPI_VERSION)
 
-gen-go-client: gen-openapi-spec ## Generate Go client from OpenAPI spec
+gen-go-client: gen-openapi-spec ## Generate Go client from OpenAPI spec (uses oapi-codegen by default)
 	@echo "Generating Go client..."
 	./bin/gen --version=$(CAPI_VERSION) --language=go
 

README.md

@@ -79,7 +79,7 @@ The `bin/gen` script provides a flexible way to generate SDKs for different lang
 ### Usage
 ```bash
 # Generate SDK
-./bin/gen --version=VERSION --language=LANGUAGE [--output=PATH]
+./bin/gen --version=VERSION --language=LANGUAGE [--output=PATH] [--generator=GENERATOR]
 
 # Prepare specifications (download and create YAML files)
 ./bin/gen prepare --version=VERSION
@@ -88,11 +88,22 @@ The `bin/gen` script provides a flexible way to generate SDKs for different lang
 ./bin/gen merge --version=VERSION
 ```
 
+### Generator Options
+
+The script supports multiple code generators:
+- **oapi-codegen** (default for Go) - Generates a single, clean Go file with types and client
+- **openapi-generator** (default for other languages) - Full-featured generator with many customization options
+
 ### Examples
 
 #### Generate Go SDK for latest CAPI version (3.195.0)
 ```bash
+# Using default oapi-codegen generator (creates single client.go file)
 ./bin/gen --version=3.195.0 --language=go
+# Output: ./sdk/3.195.0/go/capiclient/client.go
+
+# Using openapi-generator (creates multiple files)
+./bin/gen --version=3.195.0 --language=go --generator=openapi-generator
 # Output: ./sdk/3.195.0/go/
 ```
 
@@ -138,11 +149,51 @@ Run `./bin/gen --help` to see the full list of supported languages.
 
 After generating an SDK, you may need to:
 
-1. **Go**: Run `go mod tidy` in the generated directory
+1. **Go**: 
+   - With oapi-codegen: `go.mod` is automatically created and `go mod tidy` is run
+   - With openapi-generator: Run `go mod tidy` in the generated directory
 2. **Ruby**: Build the gem with `gem build *.gemspec`
 3. **Python**: Install with `pip install -e .`
 4. **Java**: Build with Maven or Gradle
 
+## Publishing Go Client
+
+The repository includes an automated workflow for publishing the Go client to a separate repository for easy consumption.
+
+### Manual Publishing
+
+```bash
+# Generate the Go client
+./bin/gen --version=3.195.0 --language=go
+
+# Publish to github.com/cloudfoundry-community/capi-openapi-go-client
+./bin/publish --version=3.195.0
+
+# Dry run to preview what will be published
+./bin/publish --version=3.195.0 --dry-run
+
+# Force overwrite if tag already exists
+./bin/publish --version=3.195.0 --force
+```
+
+### Automated Publishing via GitHub Actions
+
+1. Go to the [Actions tab](../../actions)
+2. Select "Publish Go Client" workflow
+3. Click "Run workflow"
+4. Enter the CAPI version (e.g., 3.195.0)
+5. Optionally check "Force" to overwrite existing tags
+
+The published Go module will be available at:
+```go
+import "github.com/cloudfoundry-community/capi-openapi-go-client/capiclient/v3"
+```
+
+### Publishing Requirements
+
+- **SSH Deploy Key**: The GitHub Actions workflow requires a deploy key secret (`CAPI_GO_CLIENT_DEPLOY_KEY`) with write access to the target repository
+- **Target Repository**: `github.com/cloudfoundry-community/capi-openapi-go-client` must exist and be configured to accept the deploy key
+
 ## Version Information
 
 | Component | Version |
@@ -210,10 +261,14 @@ capi/
 └── 3.195.0.openapi.json  (generated)
 bin/
 ├── gen           (main processing script for prepare, merge, and SDK generation)
+├── publish       (publishes Go client to separate repository)
 └── validate      (OpenAPI spec validation script)
 sdk/
 └── VERSION/
     └── LANGUAGE/ (generated SDKs)
+.github/
+└── workflows/
+    └── publish-go-client.yml (automated publishing workflow)
 ```
 
 ### Validation

bin/gen

@@ -22,12 +22,14 @@ my $command;
 my $capi_version;
 my $language;
 my $output_path;
+my $generator;
 my $help;
 
 GetOptions(
     'version=s' => \$capi_version,
     'language=s' => \$language,
     'output=s' => \$output_path,
+    'generator=s' => \$generator,
     'help' => \$help,
 ) or die usage();
 
@@ -51,8 +53,20 @@ if ($command eq 'prepare') {
     merge_openapi_spec($capi_version);
 } elsif ($capi_version && $language) {
     # Generate SDK (original functionality)
+    # Set default generator based on language
+    if ($language eq 'go' && !$generator) {
+        $generator = 'oapi-codegen';
+    } else {
+        $generator //= 'openapi-generator';
+    }
+    
     # Set default output path if not provided
-    $output_path //= File::Spec->catfile($project_root, 'sdk', $capi_version, $language);
+    if ($language eq 'go') {
+        # For Go, append the package name to the path
+        $output_path //= File::Spec->catfile($project_root, 'sdk', $capi_version, $language, 'capiclient');
+    } else {
+        $output_path //= File::Spec->catfile($project_root, 'sdk', $capi_version, $language);
+    }
 
     # Validate inputs
     validate_inputs();
@@ -79,6 +93,8 @@ SDK Generation Options:
   
 Optional options:
   --output=PATH       Output directory (default: ./sdk/VERSION/LANGUAGE/)
+  --generator=GEN     Generator to use: openapi-generator, oapi-codegen
+                      (default: oapi-codegen for Go, openapi-generator for others)
   --help              Show this help message
 
 Supported languages:
@@ -100,7 +116,8 @@ Supported languages:
 Examples:
   $0 prepare --version=3.195.0
   $0 merge --version=3.195.0
-  $0 --version=3.195.0 --language=go
+  $0 --version=3.195.0 --language=go                    # Uses oapi-codegen by default
+  $0 --version=3.195.0 --language=go --generator=openapi-generator
   $0 --version=3.181.0 --language=python --output=/tmp/capi-python-sdk
 EOF
 }
@@ -113,12 +130,21 @@ sub validate_inputs {
             "Please run './bin/gen merge --version=$capi_version' first to generate the specification.\n";
     }
 
-    # Check if openapi-generator is available
-    my $generator_check = `which openapi-generator 2>/dev/null || which openapi-generator-cli 2>/dev/null`;
-    chomp $generator_check;
-    unless ($generator_check) {
-        die "Error: openapi-generator-cli not found.\n" .
-            "Please run 'make deps' to install dependencies.\n";
+    # Check if selected generator is available
+    if ($generator eq 'oapi-codegen') {
+        my $generator_check = `which oapi-codegen 2>/dev/null`;
+        chomp $generator_check;
+        unless ($generator_check) {
+            die "Error: oapi-codegen not found.\n" .
+                "Please install it with: go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen\@latest\n";
+        }
+    } else {
+        my $generator_check = `which openapi-generator 2>/dev/null || which openapi-generator-cli 2>/dev/null`;
+        chomp $generator_check;
+        unless ($generator_check) {
+            die "Error: openapi-generator-cli not found.\n" .
+                "Please run 'make deps' to install dependencies.\n";
+        }
     }
 }
 
@@ -128,36 +154,73 @@ sub generate_sdk {
     # Create output directory if it doesn't exist
     make_path($output_path) unless -d $output_path;
 
-    # Determine which command to use (openapi-generator or openapi-generator-cli)
-    my $generator_cmd = `which openapi-generator 2>/dev/null`;
-    chomp $generator_cmd;
-    $generator_cmd = 'openapi-generator-cli' unless $generator_cmd;
-    
-    # Build the command
-    my $cmd = "$generator_cmd generate " .
-              "-i '$spec_file' " .
-              "-g '$language' " .
-              "-o '$output_path' " .
-              "--skip-validate-spec";
+    my $cmd;
+    my $result;
 
-    # Add GitHub configuration
-    my $github_org = 'cloudfoundry-community';
-    my $github_repo = "capi-openapi-${language}-client";
-    $cmd .= " --git-user-id='$github_org' --git-repo-id='$github_repo'";
-    
-    # Add language-specific options
-    my $additional_props = get_additional_properties($language);
-    $cmd .= " --additional-properties='$additional_props'" if $additional_props;
-    
-    # Execute the command
-    say "Generating $language SDK for CAPI $capi_version...";
-    say "Command: $cmd";
-    
-    my $result = system($cmd);
+    if ($generator eq 'oapi-codegen') {
+        # Use oapi-codegen for Go
+        if ($language ne 'go') {
+            die "Error: oapi-codegen only supports Go language generation.\n";
+        }
+        
+        # Build output file path
+        my $output_file = File::Spec->catfile($output_path, 'client.go');
+        
+        # Build the command
+        $cmd = "oapi-codegen -generate types,client -package capiclient '$spec_file' > '$output_file'";
+        
+        # Execute the command
+        say "Generating $language SDK for CAPI $capi_version using oapi-codegen...";
+        say "Command: $cmd";
+        
+        $result = system($cmd);
+        
+        # Generate go.mod file if successful
+        if ($result == 0) {
+            generate_go_mod($output_path, $capi_version);
+        }
+    } else {
+        # Use openapi-generator
+        # Determine which command to use (openapi-generator or openapi-generator-cli)
+        my $generator_cmd = `which openapi-generator 2>/dev/null`;
+        chomp $generator_cmd;
+        $generator_cmd = 'openapi-generator-cli' unless $generator_cmd;
+        
+        # Build the command
+        $cmd = "$generator_cmd generate " .
+                  "-i '$spec_file' " .
+                  "-g '$language' " .
+                  "-o '$output_path' " .
+                  "--skip-validate-spec";
+        
+        # Add config file if it exists for Go
+        my $config_file = File::Spec->catfile($project_root, 'openapi-generator-config.yml');
+        if ($language eq 'go' && -f $config_file) {
+            $cmd .= " -c '$config_file'";
+        }
+        
+        # Add GitHub configuration
+        my $github_org = 'cloudfoundry-community';
+        my $github_repo = "capi-openapi-${language}-client";
+        $cmd .= " --git-user-id='$github_org' --git-repo-id='$github_repo'";
+        
+        # Add language-specific options
+        my $additional_props = get_additional_properties($language);
+        $cmd .= " --additional-properties='$additional_props'" if $additional_props;
+        
+        # Execute the command
+        say "Generating $language SDK for CAPI $capi_version using openapi-generator...";
+        say "Command: $cmd";
+        
+        $result = system($cmd);
+    }
 
     if ($result == 0) {
         say "\nSDK generated successfully!";
         say "Output directory: $output_path";
+        if ($generator eq 'oapi-codegen') {
+            say "Generated file: " . File::Spec->catfile($output_path, 'client.go');
+        }
     } else {
         die "\nError: Failed to generate SDK. Exit code: " . ($result >> 8) . "\n";
     }
@@ -168,7 +231,7 @@ sub get_additional_properties {
 
     # Language-specific additional properties
     my %lang_props = (
-        'go' => 'packageName=capiclient,isGoSubmodule=true,generateInterfaces=true',
+        'go' => 'packageName=capiclient,generateInterfaces=true',
         'python' => 'packageName=capi_client,projectName=capi-client',
         'java' => 'groupId=org.cloudfoundry,artifactId=capi-client,artifactVersion=' . $capi_version,
         'javascript' => 'npmName=\@cloudfoundry/capi-client,npmVersion=' . $capi_version,
@@ -182,6 +245,55 @@ sub get_additional_properties {
     return $lang_props{$lang} // '';
 }
 
+sub generate_go_mod {
+    my ($output_dir, $version) = @_;
+    
+    my $go_mod_path = File::Spec->catfile($output_dir, 'go.mod');
+    
+    # Extract major version from version string (e.g., 3.195.0 -> v3)
+    my $major_version = '';
+    if ($version =~ /^(\d+)\./) {
+        $major_version = "/v$1" if $1 >= 2;  # Go modules use /v2, /v3, etc for v2+
+    }
+    
+    my $go_mod_content = <<EOF;
+module github.com/cloudfoundry-community/capi-openapi-go-client/capiclient${major_version}
+
+go 1.21
+
+require (
+\tgithub.com/oapi-codegen/runtime v1.1.1
+\tgopkg.in/yaml.v2 v2.4.0
+)
+
+require (
+\tgithub.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
+\tgithub.com/google/uuid v1.5.0 // indirect
+)
+EOF
+    
+    say "Creating go.mod file...";
+    open(my $fh, '>', $go_mod_path) or die "Cannot create go.mod: $!";
+    print $fh $go_mod_content;
+    close($fh);
+    
+    # Run go mod tidy to ensure dependencies are correct
+    my $original_dir = `pwd`;
+    chomp $original_dir;
+    chdir($output_dir);
+    
+    say "Running go mod tidy...";
+    my $tidy_result = system("go mod tidy");
+    
+    chdir($original_dir);
+    
+    if ($tidy_result == 0) {
+        say "go.mod created successfully!";
+    } else {
+        say "Warning: go mod tidy failed. You may need to run it manually.";
+    }
+}
+
 sub check_deps {
     my @deps = qw(spruce jq);
     for my $dep (@deps) {