A production-ready GitHub template for generating Elixir SDKs from OpenAPI specifications using openapi-generator.

✨ Automated Generation: One-command SDK generation with zero manual intervention 🔄 Auto-Regeneration: GitHub Actions automatically regenerate SDK when specs change 🏊 Connection Pooling: Built-in Finch connection pooling for optimal performance ♻️ Retry Logic: Automatic retries with exponential backoff for transient failures 📊 Telemetry: Integrated telemetry for monitoring and observability 🧪 Test Infrastructure: Comprehensive test helpers that survive regeneration 📈 Code Coverage: Automatic coverage tracking with threshold enforcement 🔍 Breaking Changes: Automatic detection of API breaking changes 📦 Hex.pm Ready: Pre-configured publishing workflow

Prerequisites: Elixir 1.18+, Erlang/OTP 26+, and OpenAPI Generator Install OpenAPI Generator via: brew install openapi-generator (macOS/Linux) or npm install -g @openapitools/openapi-generator-cli

Click the "Use this template" button on GitHub to create your own repository.

./scripts/setup.sh

This interactive script will prompt you for:

• Package name (e.g., my_api_client)
• Module name (e.g., MyApiClient)
• Author information
• GitHub repository details
• OpenAPI specification location

./scripts/regenerate.sh

This will:

• Validate your OpenAPI spec
• Generate the SDK code
• Run post-processing
• Format the code
• Install dependencies
• Run tests

mix test
mix credo
mix dialyzer

elixir-sdk-generator/
├── .github/workflows/      # CI/CD pipelines
│   ├── test.yml           # Test on every push
│   ├── regenerate-sdk.yml # Auto-regenerate SDK
│   ├── publish.yml        # Publish to Hex.pm
│   └── breaking-changes.yml # Detect breaking changes
├── .openapi-generator/
│   └── templates/         # Custom Mustache templates
├── config/                # Elixir configuration
├── lib/                   # Generated SDK code (disposable)
├── scripts/               # Automation scripts
├── test/                  # Tests (persistent, never regenerated)
│   ├── unit/
│   ├── integration/
│   └── support/
├── generator-config.yaml  # OpenAPI Generator config
└── openapi-spec.yaml     # Your OpenAPI specification

# Create a connection
conn = MySDK.Connection.new()

# Make API calls
{:ok, response} = MySDK.Api.Users.get_user(conn, user_id)

# Custom base URL
conn = MySDK.Connection.new(base_url: "https://api.example.com")

# Custom timeout
conn = MySDK.Connection.new(timeout: 60_000)

# Custom retry configuration
conn = MySDK.Connection.new(
  retry: [
    max_retries: 5,
    delay: 200,
    max_delay: 10_000
  ]
)

# config/runtime.exs
config :my_sdk,
  base_url: System.get_env("API_BASE_URL", "https://api.example.com"),
  pool_size: String.to_integer(System.get_env("HTTP_POOL_SIZE", "25"))

Edit openapi-spec.yaml with your API changes.

./scripts/regenerate.sh

Add tests for new endpoints in test/unit/ or test/integration/:

defmodule MySDK.Api.UsersTest do
  use TestCase

  test "creates a user" do
    conn = Connection.new(base_url: MockServer.url(bypass))
    assert {:ok, response} = Users.create_user(conn, %{name: "Test"})
  end
end

git add .
git commit -m "Add user creation endpoint"
git push

Runs on every push and PR:

• Tests across multiple Elixir/OTP versions
• Code formatting checks
• Credo linting
• Dialyzer type checking
• Code coverage with threshold enforcement

Automatically triggered when:

• openapi-spec.yaml changes
• Manual workflow dispatch
• Weekly schedule (configurable)

Creates a PR with regenerated SDK code.

Triggered on version tags (v*.*.*):

• Runs all tests
• Publishes to Hex.pm
• Creates GitHub release

# Bump version in mix.exs, then:
git tag v1.0.0
git push origin v1.0.0

Runs on PRs that modify:

• OpenAPI spec
• API modules

Detects and reports:

• Breaking changes in API spec
• Removed functions
• Modified signatures

Modify templates in .openapi-generator/templates/ to customize generated code:

• connection.ex.mustache - HTTP client configuration
• mix.exs.mustache - Mix project file
• application.ex.mustache - Application supervisor
• README.md.mustache - Generated README

Files listed in .openapi-generator-ignore are never overwritten:

• All configuration files
• All tests
• All scripts
• Custom documentation

Edit scripts/post-generate.sh to add custom post-processing:

• Code transformations
• Additional file generation
• Custom validation

mix test

mix coveralls
mix coveralls.html  # Generate HTML report

mix test test/integration/

mix test test/unit/connection_test.exs

mix format

mix credo --strict

mix dialyzer

./scripts/publish.sh

This script will:

• Run all tests
• Check code formatting
• Verify version
• Build documentation
• Publish to Hex.pm
• Create git tag

Push a version tag to trigger automatic publishing:

# Update version in mix.exs
git add mix.exs
git commit -m "Bump version to 1.0.0"
git tag v1.0.0
git push origin main --tags

Edit generator-config.yaml to customize SDK generation:

additionalProperties:
  packageName: "my_api_client"
  moduleName: "MyApiClient"
  packageVersion: "1.0.0"

Required secrets for workflows:

• HEX_API_KEY - For publishing to Hex.pm (get from mix hex.user auth)

See CONTRIBUTING.md for development guidelines.

See CHANGELOG.md for version history.

• OpenAPI Generator
• Elixir Tesla
• Finch
• Hex.pm

• Open an issue on GitHub
• Check existing issues for solutions
• Review the documentation

Generated with ❤️ using the Elixir SDK Generator Template