feat(codegen): sample generator

.github/workflows/codegen-ci.yml

@@ -7,12 +7,14 @@ on:
       - main
     paths:
       - 'internal/cmd/codegen/**'
+      - 'openapi.json'
       - '.github/workflows/codegen-ci.yml'
   pull_request:
     branches:
       - main
     paths:
       - 'internal/cmd/codegen/**'
+      - 'openapi.json'
       - '.github/workflows/codegen-ci.yml'
 
 env:

.github/workflows/release-code-samples.yaml

@@ -0,0 +1,124 @@
+name: Release Code Samples
+
+on:
+  release:
+    types:
+      - published
+
+concurrency:
+  group: release-code-samples-${{ github.event.release.tag_name }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  sync-go-code-samples:
+    name: Sync Go code samples
+    runs-on: ubuntu-latest
+    env:
+      TARGET_REPOSITORY: sumup/sumup-developer
+      TARGET_BRANCH: automation/go-code-samples
+      TARGET_FILE: src/codesamples/go.json
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: refs/tags/${{ github.event.release.tag_name }}
+          persist-credentials: false
+
+      - name: Install Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version-file: internal/cmd/codegen/go.mod
+
+      - name: Create GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          app-id: ${{ secrets.SUMUP_BOT_APP_ID }}
+          private-key: ${{ secrets.SUMUP_BOT_PRIVATE_KEY }}
+          owner: sumup
+          repositories: sumup-developer
+
+      - name: Checkout target repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: ${{ env.TARGET_REPOSITORY }}
+          ref: main
+          token: ${{ steps.app-token.outputs.token }}
+          path: sumup-developer
+          persist-credentials: true
+
+      - name: Get GitHub App User ID
+        id: get-user-id
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+
+      - name: Configure git
+        run: |
+          git config --global user.name '${{ steps.app-token.outputs.app-slug }}[bot]'
+          git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com'
+
+      - name: Prepare target branch
+        working-directory: sumup-developer
+        run: |
+          git fetch origin "${{ env.TARGET_BRANCH }}:refs/remotes/origin/${{ env.TARGET_BRANCH }}" || true
+          git checkout -B "${{ env.TARGET_BRANCH }}" origin/main
+
+      - name: Generate Go code samples
+        working-directory: internal/cmd/codegen
+        run: |
+          mkdir -p "../../../sumup-developer/$(dirname "${{ env.TARGET_FILE }}")"
+          go run . samples \
+            --sdk-version-file ../../../internal/version.go \
+            --out "../../../sumup-developer/${{ env.TARGET_FILE }}" \
+            ../../../openapi.json
+
+      - name: Commit generated samples
+        id: commit
+        working-directory: sumup-developer
+        run: |
+          git add "${{ env.TARGET_FILE }}"
+          if git diff --cached --quiet; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git commit -m "chore: update Go code samples for ${{ github.event.release.tag_name }}"
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Push branch
+        if: steps.commit.outputs.changed == 'true'
+        working-directory: sumup-developer
+        run: git push --force-with-lease origin "${{ env.TARGET_BRANCH }}"
+
+      - name: Create or update pull request
+        if: steps.commit.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          head_ref="sumup:${{ env.TARGET_BRANCH }}"
+          pr_url="$(gh pr list \
+            --repo "${{ env.TARGET_REPOSITORY }}" \
+            --head "$head_ref" \
+            --base main \
+            --state open \
+            --json url \
+            --jq '.[0].url')"
+
+          if [ -n "$pr_url" ]; then
+            gh pr edit "$pr_url" \
+              --repo "${{ env.TARGET_REPOSITORY }}" \
+              --title "chore: update Go code samples" \
+              --body "Updates \`${{ env.TARGET_FILE }}\` from \`${{ github.repository }}\` release \`${{ github.event.release.tag_name }}\`."
+            exit 0
+          fi
+
+          gh pr create \
+            --repo "${{ env.TARGET_REPOSITORY }}" \
+            --base main \
+            --head "${{ env.TARGET_BRANCH }}" \
+            --title "chore: update Go code samples" \
+            --body "Updates \`${{ env.TARGET_FILE }}\` from \`${{ github.repository }}\` release \`${{ github.event.release.tag_name }}\`."

.gitignore

@@ -1 +1,2 @@
 .envrc
+/code-samples.json

Makefile

@@ -38,6 +38,12 @@ generate: ## Generate latest SDK
 	cd internal/cmd/codegen && go run ./... generate --out ../../.. ../../../openapi.json
 	gomarkdoc --repository.url https://github.com/sumup/sumup-go --repository.default-branch main --exclude-dirs ./internal/cmd/codegen/... --output DOCUMENTATION.md ./...
 
+CODESAMPLES_OUT ?= code-samples.json
+
+.PHONY: generate-codesamples
+generate-codesamples: ## Generate Go code samples
+	cd internal/cmd/codegen && go run ./... samples --sdk-version-file ../../../internal/version.go --out "$(abspath $(CODESAMPLES_OUT))" ../../../openapi.json
+
 .PHONY: install-tools
 install-tools: # Install development dependencies
 	cd internal/cmd/codegen && go install ./cmd/go-sdk-gen

internal/cmd/codegen/README.md

@@ -5,3 +5,23 @@
 </div>
 
 Code generator for [sumup-go](https://github.com/sumup/sumup-go).
+
+## Go SDK
+
+The `generate` command reads `openapi.json` and generates the Go client, services, request types, and response types in the repository root. Generate the SDK and refresh its API documentation from the repository root with:
+
+```shell
+make generate
+```
+
+## Go Code Samples
+
+The `samples` command generates a deterministic, versioned JSON catalog of Go examples from the same intermediate representation used to generate the SDK. Each catalog entry contains a complete, formatted Go program. Named OpenAPI request examples produce separate entries.
+
+Generate a catalog from the repository root with:
+
+```shell
+make generate-codesamples
+```
+
+The target writes `code-samples.json` in the repository root by default. Set `CODESAMPLES_OUT` to use another path. Every generated program is compiled by the codegen test suite. When an SDK release is published, the release workflow regenerates the catalog from that tag and opens or updates a pull request in `sumup/sumup-developer`; the generated JSON is not committed to this repository.

internal/cmd/codegen/generate.go

@@ -6,7 +6,6 @@ import (
 	"os"
 	"os/exec"
 
-	"github.com/pb33f/libopenapi"
 	"github.com/urfave/cli/v2"
 
 	"github.com/sumup/sumup-go/internal/cmd/codegen/pkg/builder"
@@ -29,26 +28,16 @@ func Generate() *cli.Command {
 				return fmt.Errorf("create output directory %q: %w", out, err)
 			}
 
-			spec, err := os.ReadFile(specs)
+			spec, err := loadOpenAPIDocument(specs)
 			if err != nil {
-				return fmt.Errorf("read specs: %w", err)
-			}
-
-			doc, err := libopenapi.NewDocument(spec)
-			if err != nil {
-				return fmt.Errorf("load openapi document: %w", err)
-			}
-
-			model, err := doc.BuildV3Model()
-			if err != nil {
-				return fmt.Errorf("build openapi v3 model: %w", err)
+				return err
 			}
 
 			builder := builder.New(builder.Config{
 				Out: out,
 			})
 
-			if err := builder.Load(&model.Model); err != nil {
+			if err := builder.Load(spec); err != nil {
 				return fmt.Errorf("load spec: %w", err)
 			}
 

internal/cmd/codegen/main.go

@@ -28,6 +28,7 @@ func App() *cli.App {
 		},
 		Commands: []*cli.Command{
 			Generate(),
+			Samples(),
 		},
 	}
 }

internal/cmd/codegen/openapi.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/pb33f/libopenapi"
+	v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
+)
+
+func loadOpenAPIDocument(filename string) (*v3.Document, error) {
+	spec, err := os.ReadFile(filename)
+	if err != nil {
+		return nil, fmt.Errorf("read specs: %w", err)
+	}
+
+	document, err := libopenapi.NewDocument(spec)
+	if err != nil {
+		return nil, fmt.Errorf("load openapi document: %w", err)
+	}
+
+	model, err := document.BuildV3Model()
+	if err != nil {
+		return nil, fmt.Errorf("build openapi v3 model: %w", err)
+	}
+
+	return &model.Model, nil
+}

internal/cmd/codegen/pkg/builder/intermediate_representation.go

@@ -50,6 +50,7 @@ type StructField struct {
 	Comment string
 
 	Parameter *v3.Parameter
+	Schema    *base.SchemaProxy
 }
 
 type EnumOption[E cmp.Ordered] struct {