Overview

Mizu Contract includes built-in SDK generators that create native, fully-typed client libraries from your contract definitions. Generate idiomatic code for each language with resource-based API access and first-class streaming support.

What is SDK Generation?

SDK generation creates client libraries from your API contract. Instead of writing HTTP client code by hand for each language, you define your API once and generate clients automatically.

Contract Definition (api.yaml)
           │
           ▼
    ┌──────────────────┐
    │ mizu contract gen│
    │   (Go/Py/TS)     │
    └──────────────────┘
           │
           ▼
  Native Client Library
  (Types + Client + Streaming)

Quick Start

Generate SDK clients using the CLI:

# Generate a Go SDK client
mizu contract gen api.yaml --client --lang go --output ./sdk/go

# Generate a Python SDK client
mizu contract gen api.yaml --client --lang python --output ./sdk/python

# Generate a TypeScript SDK client
mizu contract gen api.yaml --client --lang typescript --output ./sdk/typescript

# Generate all languages at once
mizu contract gen api.yaml --client --lang all --output ./sdk

Why Use Native SDK Generators?

Benefits Over Manual Client Code

Aspect	Manual Code	Generated SDK
Type Safety	Error-prone, manual sync	Always matches server
Maintenance	Update everywhere	Regenerate once
Consistency	Varies by author	Uniform patterns
Time to Ship	Hours per language	Seconds

Benefits Over Generic OpenAPI-Based Generation

Feature	Generic Generators	Mizu SDK Generators
Code Style	Generic, verbose	Idiomatic, minimal
Dependencies	Often many	Minimal (stdlib-focused)
API Feel	HTTP-centric	Resource-oriented
Streaming	Limited support	First-class SSE
Size	Large output	Compact, focused

When to use OpenAPI generators? OpenAPI generators support 40+ languages and have mature tooling. Use them when you need languages Mizu doesn’t support natively, or when you need OpenAPI compatibility with other tools. See Client Generation for OpenAPI approaches.

Available SDK Generators

Mizu provides native SDK generators for three languages:

Go

Zero dependencies, stdlib only. Fluent resource-based API with EventStream for streaming.

Python

Modern Python with type hints. Sync and async clients using httpx.

TypeScript

Runtime agnostic (Node/Bun/Deno). AsyncIterable streaming with full type inference.

Quick Comparison

Feature	Go SDK	Python SDK	TypeScript SDK
Output	Single `.go` file	uv/pip project	npm package
HTTP Client	`net/http`	`httpx`	native `fetch`
Streaming	`EventStream[T]`	Iterator/AsyncIterator	`AsyncIterable<T>`
Dependencies	None (stdlib)	httpx	None
Runtimes	Go 1.18+	Python 3.8+	Node 18+/Bun/Deno

How It Works

Step 1: Define Your Contract

Create a contract definition in YAML:

# api.yaml
name: TodoAPI
description: Todo list API

defaults:
  base_url: http://localhost:8080

resources:
  - name: todos
    description: Manage todo items
    methods:
      - name: create
        description: Create a new todo
        input: CreateTodoInput
        output: Todo
        http:
          method: POST
          path: /todos
      - name: list
        description: List all todos
        output: TodoList
        http:
          method: GET
          path: /todos
      - name: get
        description: Get a todo by ID
        input: GetTodoInput
        output: Todo
        http:
          method: GET
          path: /todos/{id}
      - name: delete
        description: Delete a todo
        input: DeleteTodoInput
        http:
          method: DELETE
          path: /todos/{id}

types:
  - name: Todo
    kind: struct
    fields:
      - name: id
        type: string
      - name: title
        type: string
      - name: done
        type: bool
      - name: created_at
        type: time.Time
        optional: true
  - name: TodoList
    kind: slice
    elem: Todo
  - name: CreateTodoInput
    kind: struct
    fields:
      - name: title
        type: string
  - name: GetTodoInput
    kind: struct
    fields:
      - name: id
        type: string
  - name: DeleteTodoInput
    kind: struct
    fields:
      - name: id
        type: string

Step 2: Generate SDK Clients

# Generate Go SDK
mizu contract gen api.yaml --client --lang go --output ./sdk/go --package todoclient

# Generate Python SDK
mizu contract gen api.yaml --client --lang python --output ./sdk/python --package todoclient --version 1.0.0

# Generate TypeScript SDK
mizu contract gen api.yaml --client --lang typescript --output ./sdk/typescript --package todoclient --version 1.0.0

Step 3: Use the Generated Clients

package main

import (
    "context"
    "fmt"
    "todoclient"
)

func main() {
    client := todoclient.NewClient("http://localhost:8080")
    ctx := context.Background()

    todo, err := client.Todos.Create(ctx, &todoclient.CreateTodoInput{
        Title: "Learn Mizu SDKs",
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Created: %s\n", todo.ID)
}

from todoclient import Client

client = Client(base_url="http://localhost:8080")

todo = client.todos.create(title="Learn Mizu SDKs")
print(f"Created: {todo.id}")

import { Client } from 'todoclient';

const client = new Client({ baseURL: 'http://localhost:8080' });

const todo = await client.todos.create({ title: 'Learn Mizu SDKs' });
console.log(`Created: ${todo.id}`);

CLI Reference

Command Syntax

mizu contract gen <file> [flags]

Flags

Flag	Short	Description	Default
`--lang`		Target language: `go`, `golang`, `python`, `py`, `typescript`, `ts`, `all`	`typescript`
`--output`	`-o`	Output directory	Same as input file
`--package`		Package/module name	Derived from service name
`--version`		Package version (Python/TypeScript)	`0.0.0`
`--client`	`-c`	Generate full SDK client (not just types)	`false`

Examples

# Types only (lightweight, no HTTP client)
mizu contract gen api.yaml --lang go --package api

# Full SDK client for Go
mizu contract gen api.yaml --client --lang go --output ./sdk/go

# Full SDK client for Python with version
mizu contract gen api.yaml --client --lang python --output ./sdk/python --version 1.0.0

# Full SDK client for TypeScript
mizu contract gen api.yaml --client --lang typescript --output ./sdk/typescript

# All languages at once
mizu contract gen api.yaml --client --lang all --output ./sdk

Choosing the Right Approach

Use this decision matrix to choose between SDK generation and OpenAPI:

If you need…	Use
Go, Python, or TypeScript client	Native SDK generators
Maximum type safety	Native SDK generators
Minimal dependencies	Native SDK generators
Streaming (SSE) support	Native SDK generators
Other languages (Java, Ruby, etc.)	OpenAPI generators
OpenAPI ecosystem compatibility	OpenAPI generators
Both approaches	Both! Generate native SDKs and serve `/openapi.json`

CI/CD Integration

Regenerate SDKs on contract changes:

# .github/workflows/sdk.yml
name: Generate SDKs

on:
  push:
    paths:
      - 'api.yaml'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Mizu CLI
        run: go install github.com/go-mizu/mizu/cmd/cli@latest

      - name: Generate SDKs
        run: |
          mizu contract gen api.yaml --client --lang go --output ./sdk/go
          mizu contract gen api.yaml --client --lang python --output ./sdk/python
          mizu contract gen api.yaml --client --lang typescript --output ./sdk/typescript

      - name: Commit SDKs
        run: |
          git add sdk/
          git commit -m "chore: regenerate SDKs" || true
          git push

What’s Next?

Go

Complete guide to generating and using Go SDKs

Python

Complete guide to generating and using Python SDKs

TypeScript

Complete guide to generating and using TypeScript SDKs

OpenAPI Generation

Alternative approach using OpenAPI specification

Getting Started

Core Concepts

Transports

SDKs

Advanced

Reference

What is SDK Generation?

Quick Start

Why Use Native SDK Generators?

Benefits Over Manual Client Code

Benefits Over Generic OpenAPI-Based Generation

Available SDK Generators

Go

Python

TypeScript

Quick Comparison

How It Works

Step 1: Define Your Contract

Step 2: Generate SDK Clients

Step 3: Use the Generated Clients

CLI Reference

Command Syntax

Flags

Examples

Choosing the Right Approach

CI/CD Integration

What’s Next?

Go

Python

TypeScript

OpenAPI Generation

See Also

​What is SDK Generation?

​Quick Start

​Why Use Native SDK Generators?

​Benefits Over Manual Client Code

​Benefits Over Generic OpenAPI-Based Generation

​Available SDK Generators

Go

Python

TypeScript

​Quick Comparison

​How It Works

​Step 1: Define Your Contract

​Step 2: Generate SDK Clients

​Step 3: Use the Generated Clients

​CLI Reference

​Command Syntax

​Flags

​Examples

​Choosing the Right Approach

​CI/CD Integration

​What’s Next?

Go

Python

TypeScript

OpenAPI Generation

​See Also

What is SDK Generation?

Quick Start

Why Use Native SDK Generators?

Benefits Over Manual Client Code

Benefits Over Generic OpenAPI-Based Generation

Available SDK Generators

Quick Comparison

How It Works

Step 1: Define Your Contract

Step 2: Generate SDK Clients

Step 3: Use the Generated Clients

CLI Reference

Command Syntax

Flags

Examples

Choosing the Right Approach

CI/CD Integration

What’s Next?

See Also