First SDK

Step-by-step walkthrough building a complete SDK project with tests, CI, and docs.

This walkthrough creates a complete, publishable SDK from an OpenAPI specification — including project structure, CI/CD, tests, and documentation.

Step 1: Scaffold the Project

autosdk init WeatherApi WeatherApiClient \
  "https://api.weather.example/openapi.json" \
  MyCompany \
  --add-mkdocs --add-tests

Step 2: Review the Structure

WeatherApi/
├── WeatherApi.slnx                    # Solution file
├── src/
│   ├── libs/WeatherApi/
│   │   ├── WeatherApi.csproj          # Library project
│   │   ├── openapi.yaml              # Downloaded spec
│   │   ├── generate.sh               # Regeneration script
│   │   └── Generated/                # Auto-generated code
│   └── tests/IntegrationTests/
│       └── IntegrationTests.csproj
├── docs/                              # MkDocs Material site
└── .github/workflows/
    └── auto-update.yml               # Auto-update spec every 3 hours

Step 3: Customize `generate.sh`

The generate.sh script is the single source of truth for regeneration. Open it and adjust:

#!/bin/bash
set -e

# Download the latest spec
curl -s https://api.weather.example/openapi.json -o openapi.json

# Generate the SDK
autosdk generate openapi.json \
  --namespace MyCompany.WeatherApi \
  --clientClassName WeatherApiClient \
  --output Generated \
  --targetFramework net10.0

Common Customizations

Add security scheme if needed:

autosdk generate openapi.json \
  --namespace MyCompany.WeatherApi \
  --clientClassName WeatherApiClient \
  --output Generated \
  --security-scheme Http:Header:Bearer

Patch the spec inline (common for specs with issues):

# Fix apiKey auth to Bearer
cat openapi.json | jq '
  .components.securitySchemes = {
    "BearerAuth": {"type": "http", "scheme": "bearer"}
  } |
  .security = [{"BearerAuth": []}]
' > openapi-patched.json

autosdk generate openapi-patched.json \
  --namespace MyCompany.WeatherApi \
  --clientClassName WeatherApiClient \
  --output Generated

Step 4: Build and Test

# Build the SDK
dotnet build WeatherApi.slnx

# Run tests (if API key is available)
WEATHER_API_KEY=your-key dotnet test src/tests/IntegrationTests/

Step 5: Add Client Extensions

Generated clients are partial classes. Add custom functionality alongside the Generated/ directory:

// src/libs/WeatherApi/WeatherApiClient.Auth.cs
namespace MyCompany.WeatherApi;

public partial class WeatherApiClient
{
    partial void Authorized(HttpRequestMessage request)
    {
        // Custom auth logic if needed
    }
}

Step 6: Publish

The generated project includes MinVer for versioning. Tag and push:

git tag v1.0.0
git push origin v1.0.0

CI will build and publish to NuGet automatically (configure your NUGET_API_KEY secret).