feat(codegen): generate validated Python code samples

.github/workflows/generate.yaml

@@ -5,6 +5,9 @@ on:
   pull_request:
     paths:
       - openapi.json
+      - codegen/**
+      - justfile
+      - sumup/_version.py
     branches:
       - main
 
@@ -42,6 +45,14 @@ jobs:
         run: go run ./... generate --out ../sumup/ ../openapi.json
         working-directory: codegen
 
+      - name: Test code generator and code samples
+        run: go test -race ./...
+        working-directory: codegen
+
+      - name: Generate code sample catalog
+        run: go run . samples --sdk-version-file ../sumup/_version.py --out /tmp/sumup-py-code-samples.json ../openapi.json
+        working-directory: codegen
+
       - name: Format
         run: uv run ruff format
 

.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-python-code-samples:
+    name: Sync Python code samples
+    runs-on: ubuntu-latest
+    env:
+      TARGET_REPOSITORY: sumup/sumup-developer
+      TARGET_BRANCH: automation/python-code-samples
+      TARGET_FILE: src/codesamples/python.json
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: refs/tags/${{ github.event.release.tag_name }}
+          persist-credentials: false
+
+      - name: Install Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: codegen/go.mod
+
+      - name: Create GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        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 Python code samples
+        working-directory: codegen
+        run: |
+          mkdir -p "../sumup-developer/$(dirname "${{ env.TARGET_FILE }}")"
+          go run . samples \
+            --sdk-version-file ../sumup/_version.py \
+            --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 Python 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 Python 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 Python code samples" \
+            --body "Updates \`${{ env.TARGET_FILE }}\` from \`${{ github.repository }}\` release \`${{ github.event.release.tag_name }}\`."

.gitignore

@@ -1,2 +1,3 @@
 __pycache__/
 sumup.egg-info/
+code-samples.json

codegen/README.md

@@ -6,10 +6,22 @@ A highly opinionated OpenAPI specs to SDK generator for [sumup-py](https://githu
 
 </div>
 
-## Quickstart
+## Python SDK
 
-Generate the SDK using:
+The `generate` command reads `openapi.json` and generates the Python client, resources, request types, and response types. Generate the SDK from the repository root with:
 
 ```sh
-go run ./... --name 'My API' ./openapi.yaml
+just generate
 ```
+
+## Python Code Samples
+
+The `samples` command generates a deterministic, versioned JSON catalog from the same intermediate representation used to generate the SDK. Each entry contains a complete Python program, and named OpenAPI request examples produce separate entries.
+
+Generate the catalog from the repository root with:
+
+```sh
+just generate-codesamples
+```
+
+The recipe writes `code-samples.json` in the repository root by default. Pass another path as its argument to use a different destination. The codegen test suite compiles every generated program, and the release workflow sends the release-tag catalog to `src/codesamples/python.json` in `sumup/sumup-developer`; generated JSON is not committed to this repository.

codegen/generate.go

@@ -4,7 +4,6 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/pb33f/libopenapi"
 	"github.com/urfave/cli/v2"
 
 	"github.com/sumup/sumup-py/codegen/pkg/builder"
@@ -30,26 +29,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)
 			}
 

codegen/main.go

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

codegen/openapi.go

@@ -0,0 +1,27 @@
+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
+}

codegen/pkg/builder/intermediate_representation.go

@@ -4,6 +4,8 @@ import (
 	"cmp"
 	"fmt"
 	"strings"
+
+	"github.com/pb33f/libopenapi/datamodel/high/base"
 )
 
 // ClassDeclaration holds the information for generating a type.
@@ -43,6 +45,8 @@ type Property struct {
 	Type string
 	// Optional field.
 	Optional bool
+	// Schema is the OpenAPI schema used to generate this property.
+	Schema *base.SchemaProxy
 
 	Comment string
 }

codegen/pkg/builder/methods.go

@@ -48,7 +48,7 @@ func (mt Method) ParamsString() string {
 	res.WriteString("self")
 	for _, p := range mt.PathParams {
 		res.WriteString(", ")
-		res.WriteString(fmt.Sprintf("%s: %s", strcase.ToSnake(p.Name), p.Type))
+		fmt.Fprintf(&res, "%s: %s", strcase.ToSnake(p.Name), p.Type)
 	}
 	needsKeywordOnly := mt.HasFlattenedBody() || len(mt.QueryFields) > 0
 	if mt.HasFlattenedBody() {
@@ -61,7 +61,7 @@ func (mt Method) ParamsString() string {
 		}
 	} else if mt.HasBody {
 		res.WriteString(", ")
-		res.WriteString(fmt.Sprintf("body: %sInput", mt.BodyType))
+		fmt.Fprintf(&res, "body: %sInput", mt.BodyType)
 	}
 	if len(mt.QueryFields) > 0 {
 		if !mt.HasFlattenedBody() {
@@ -160,7 +160,7 @@ func pathBuilder(path string) string {
 		if match == nil {
 			res.WriteString(part)
 		} else {
-			res.WriteString(fmt.Sprintf("{%s}", strcase.ToSnake(match[1])))
+			fmt.Fprintf(&res, "{%s}", strcase.ToSnake(match[1]))
 		}
 	}
 	res.WriteString(`"`)
@@ -277,6 +277,7 @@ func (b *Builder) buildQueryFields(o *v3.Operation) ([]Property, error) {
 			SerializedName: alias,
 			Type:           typeName,
 			Optional:       p.Required == nil || !*p.Required,
+			Schema:         p.Schema,
 			Comment:        parameterPropertyDoc(p.Schema.Schema()),
 		})
 	}