Skip to main content
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

AspectManual CodeGenerated SDK
Type SafetyError-prone, manual syncAlways matches server
MaintenanceUpdate everywhereRegenerate once
ConsistencyVaries by authorUniform patterns
Time to ShipHours per languageSeconds

​
Benefits Over Generic OpenAPI-Based Generation

FeatureGeneric GeneratorsMizu SDK Generators
Code StyleGeneric, verboseIdiomatic, minimal
DependenciesOften manyMinimal (stdlib-focused)
API FeelHTTP-centricResource-oriented
StreamingLimited supportFirst-class SSE
SizeLarge outputCompact, 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

FeatureGo SDKPython SDKTypeScript SDK
OutputSingle .go fileuv/pip projectnpm package
HTTP Clientnet/httphttpxnative fetch
StreamingEventStream[T]Iterator/AsyncIteratorAsyncIterable<T>
DependenciesNone (stdlib)httpxNone
RuntimesGo 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)
}

​
CLI Reference

​
Command Syntax

mizu contract gen <file> [flags]

​
Flags

FlagShortDescriptionDefault
--langTarget language: go, golang, python, py, typescript, ts, alltypescript
--output-oOutput directorySame as input file
--packagePackage/module nameDerived from service name
--versionPackage version (Python/TypeScript)0.0.0
--client-cGenerate 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 clientNative SDK generators
Maximum type safetyNative SDK generators
Minimal dependenciesNative SDK generators
Streaming (SSE) supportNative SDK generators
Other languages (Java, Ruby, etc.)OpenAPI generators
OpenAPI ecosystem compatibilityOpenAPI generators
Both approachesBoth! 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

​
See Also