# How to add a Ruby target to an existing multi-language SDK

> Generate a Ruby client beside your TypeScript, Python and Go SDKs, give it one release version and a Ruby face, and prove it sends what the others send.

Source: https://voxgig.com/howto/add-a-ruby-sdk-target

- Audience: library-maintainer
- Level: intermediate
- Languages: ruby
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

In an sdkgen project, run `voxgig-sdkgen target add rb`, set the same `publish: version` for each target in `project.aontu`, and regenerate. The gem loads with Ruby's own `json` alone, but sends only the string keys of a data hash and has no `VERSION` constant, so add a small facade outside the generated tree. Then run one shared corpus through the TypeScript and Ruby clients, because Ruby will not report a bad rename until something calls it.

---
## You will need

Node 22 or later, Ruby 3.0 or later, an OpenAPI 3 document, and an sdkgen project that already
ships other targets. The sample's document is the Bookshelf API from the
[first sdkgen page](/howto/first-sdk-with-sdkgen), five operations on one `Book` schema.
`generate.sh` scaffolds it with `ts`, `py` and `go`, adds `rb`, and also runs Kiota and Swagger
Codegen. Their output is committed under `generated/`, so every command on the page runs offline
against a stand-in server on `127.0.0.1`.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hand-written Faraday client](https://lostisland.github.io/faraday/) | One API, few operations, and Ruby callers who expect keyword arguments and Structs | Every operation and field written by hand, and a field the API adds is dropped until you add it | The API changes often, or you ship it in four languages |
| [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/quickstarts/ruby) | You already run Kiota for other languages and want the same request-builder shape in Ruby | No `gemspec`, six runtime gems in its quickstart, and a Ruby target its own release labels preview | You need a publishable gem out of the generator |
| [OpenAPI Generator ruby generator, `faraday` library](https://openapi-generator.tech/docs/generators/ruby/) | You run OpenAPI Generator for other languages and want the Ruby gem on Faraday | Typhoeus by default, so the `faraday` library must be chosen, and a template set per language to customize | You want one model for every target |
| [sdkgen `rb` target](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/add-a-target.md) | An sdkgen project whose other targets should share the Ruby gem's model, features and version | Symbol keys in a data hash dropped unsent, no `VERSION` constant, and `require_paths` of `.`, so a facade does the Ruby part | Ruby is your only language, or idiom matters more than parity |
| [Swagger Codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generators-configuration/) | You want a conventional gem, `lib/` and a `VERSION` constant, from one config file | Typhoeus underneath, so the system's `libcurl` too, and an options hash on every call | The machines that run the gem lack `libcurl` |

Voxgig maintains sdkgen. It is one of five options here, not the recommendation.

Swagger Codegen writes the most conventional gem of the generators run here, at the cost of
`libcurl` on every host. Kiota keeps the request-builder shape your other Kiota clients have, with
six gems to load and no package. sdkgen keeps Ruby in step with three other targets from one
model, and leaves the idiom to a facade you own.

## Add the target and put every port on one version

`target add` copies the target's model into `.sdk/model/target/`, and the next `generate` writes
`rb/` beside `ts/`, `py/` and `go/`:

```bash title="generate.sh"
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json -t ts -t py -t go
(cd bookshelf-sdk/.sdk && npm run generate)
(cd bookshelf-sdk/.sdk && npx voxgig-sdkgen target add rb)
cat lockstep.aontu >> bookshelf-sdk/.sdk/model/project.aontu
(cd bookshelf-sdk/.sdk && npm run generate)
```

Each manifest declares `0.0.1` until told otherwise. The
[model reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) names the
key, `main.kit.target.<t>.publish.version`, one per target, so a lockstep release sets all four:

```aontu title="lockstep.aontu"
# One release version for every target, so the four packages move in lockstep.
main: kit: target: ts: publish: version: '1.4.0'
main: kit: target: py: publish: version: '1.4.0'
main: kit: target: go: publish: version: '1.4.0'
main: kit: target: rb: publish: version: '1.4.0'

# The gem name RubyGems will list, in place of the derived one.
main: kit: target: rb: publish: registry: package: 'bookshelf'
```

```bash
node versions.mjs
```

```text output
ts  package.json            @voxgig-sdk/bookshelf-sdk   1.4.0
py  pyproject.toml          voxgig-sdk-bookshelf-sdk    1.4.0
rb  Bookshelf_sdk.gemspec   bookshelf                   1.4.0
rb  config.rb               (runtime config)            1.4.0
go  core/config.go          (runtime config)            1.4.0
one version across every target: 1.4.0
```

`project.aontu` is the project's own model, which the model reference says carries over every
update, so the version survives regeneration. The other package names keep their derived forms until you set them the same way.

## Give the gem a Ruby face

The generated gem names its methods in snake case, `list`, `load` and `data_get`, and declares
`required_ruby_version` `>= 3.0`.[^1] Its data hashes are string-keyed: `create(title: "Ulysses")`
reaches the stand-in as an empty body, because the symbol keys are dropped. It keeps its version
inside a config hash. `bookshelf.rb` sits outside `generated/`, so `npm run generate`
never touches it:

```ruby title="bookshelf.rb"
module Bookshelf
  # The release version that .sdk/model/project.aontu sets for every target.
  VERSION = BookshelfConfig.make_config.dig("main", "version")

  Book = Struct.new(:id, :title, :author, :published, keyword_init: true) do
    def self.from(record) = new(**record.transform_keys(&:to_sym).slice(*members))
  end
```

`books.find(id: "b2")` then reads as Ruby, a misspelled keyword raises `ArgumentError`, and
`Bookshelf::VERSION` follows `project.aontu`. The `Struct` is the cost: a field the API adds
reaches callers only after you add it to the member list.

## Prove the Ruby client sends what the others send

`corpus.json` names six cases, each with the request it must cause and the result it must
return. `corpus.mjs` runs every case against a fresh stand-in through the compiled TypeScript SDK,
through the Ruby SDK, and through the facade, and records what the stand-in received.

```bash
node corpus.mjs
```

```text output
case                request               ts         rb sdk     rb facade
list books          GET /v1/books         pass       pass       pass
load one            GET /v1/books/b2      pass       pass       pass
create              POST /v1/books        pass       pass       pass
update              PATCH /v1/books/b1    pass       pass       pass
remove              DELETE /v1/books/b2   pass       pass       pass
load a missing id   GET /v1/books/b9      pass       pass       pass
every runner passed every case
```

The request column is the stand-in's record, not the client's. sdkgen ships a language-neutral
corpus of its own under `.sdk/test/feature`, which the generated Ruby suite runs in
`test/feature_corpus_test.rb`. That one covers the generator's features, and this one covers
your API's cases and your facade.

## Generate Ruby clients from the same document in two other tools

Kiota writes request builders, `client.books.by_book_id("b2").get`, with no `gemspec`. Its
[Ruby quickstart](https://learn.microsoft.com/en-us/openapi/kiota/quickstarts/ruby) adds the
runtime gems to a `Gemfile` and resolves each call's Fiber with `.resume`. Swagger Codegen takes the
gem name, module, version and Ruby floor from the `-c` file its
[configuration page](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generators-configuration/)
describes, whose Ruby keys `config-help -l ruby` lists, and writes a conventional gem. OpenAPI Generator's ruby generator takes
`library=faraday`, which `generate.sh` did not run.

```bash
ruby inspect.rb
```

```text output
sdkgen rb
  gemspec               bookshelf 1.4.0
  required_ruby_version >= 3.0
  runtime dependencies  json
  require_paths         .
  VERSION constant      none
  list operation        book_entity.rb: def list(reqmatch = nil, ctrl = nil)
Kiota
  gemspec               none
  VERSION constant      none
  list operation        books_request_builder.rb: def get(request_configuration = nil)
Swagger Codegen
  gemspec               bookshelf 1.4.0
  required_ruby_version >= 3.0
  runtime dependencies  json, typhoeus
  require_paths         lib
  VERSION constant      lib/bookshelf/version.rb
  list operation        default_api.rb: def list_books(opts = {})
```

None of the three generated operation methods takes keyword arguments. `generate.sh` also recorded the two measures. The first
is the gems installed into an empty gem directory before a first successful call: 17 for the six
gems Kiota's quickstart names, four for Typhoeus, and eight for Faraday. sdkgen's gem names only
`json`, which ships with Ruby. Adding one field, `isbn`, to `Book` changed 2 Kiota files and 3
Swagger Codegen files. sdkgen changed 4 Ruby files in a run that regenerated all four targets.
Each count includes the docs and lock files the tool rewrote. The hand-written client and the facade each need
one line by hand.

## Check it worked

Eight tests run the corpus, the versions, the facade, and the generated gem's handling of symbol
keys.

```bash
node --test ruby-target.test.mjs
```

```text output
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 3138.351872
```

One feeds `verdict` a wrong path and a wrong field, so the corpus is shown to fail. Another sends
`a/b` as an id and expects the stand-in to record `/v1/books/a%2Fb`, with `..` refused before any
request.

## When it goes wrong

A method is renamed in the facade, `find` to `fetch`, and a caller still calls `find`. The file
parses and loads, because Ruby resolves the method at call time. Only the corpus calls it.

```bash
node pitfall.mjs
```

```text output
ruby -c:          Syntax OK
require and load: Bookshelf::VERSION is 1.4.0

case                request               rb facade
list books          GET /v1/books         pass
load one            GET /v1/books/b2      NoMethodError
create              POST /v1/books        pass
update              PATCH /v1/books/b1    pass
remove              DELETE /v1/books/b2   pass
load a missing id   GET /v1/books/b9      NoMethodError
2 of 6 cases failed
```

A code review reads the rename and approves it. Make the corpus a required check for the Ruby
job, with a case for every public method of the facade.

The versions drift after a release. A target missing from `lockstep.aontu` stays at `0.0.1`.
Run `versions.mjs` before tagging.

The gem installs but `require "bookshelf"` fails. The generated `gemspec` sets `require_paths` to
`.` and the entry file is `Bookshelf_sdk.rb`, so a caller writes `require "Bookshelf_sdk"`, or the
facade gives them a conventional name.

## When not to do this

Do not add sdkgen's Ruby target to a gem whose callers judge it on idiom alone. Its value is
parity with your other targets, and the facade is yours to write and keep in step.

Do not ship Kiota's Ruby output as a gem without writing the `gemspec` it leaves out, and pin the
runtime gems `kiota info` lists, since its changelog moved Ruby to preview in 1.39.0.[^2]

Do not pick Swagger Codegen for hosts without `libcurl`. Pick it when a conventional gem, `lib/`
and `VERSION` included, matters more than parity, because it writes one from a config file.
Kiota is the better choice when your other clients are Kiota clients already.

Do not trust a code review to prove a Ruby port. Run the corpus.

## Related how-tos

- [Decide which SDK language to add next](/howto/decide-which-sdk-language-to-add-next)

- [Choose lockstep or independent versions across your SDKs](/howto/lockstep-or-independent-versions-across-sdk-languages)

- [Design the case shape of a language-neutral test corpus](/howto/design-the-case-shape-of-a-test-corpus)

- [Evaluate a third-tier SDK target before you ship it](/howto/evaluate-a-third-tier-sdk-target)

- [Audit an SDK generator's language coverage](/howto/audit-generator-language-coverage-claims)

## Last verified

Verified 2026-11-21 against Node 22.23.5, Ruby 3.3.6, `@voxgig/create-sdkgen` 0.31.9,
`@voxgig/sdkgen` 4.44.3, Kiota 1.39.0 and Swagger Codegen 3.0.85. Every output block is what the
command preceding it printed. The three generators ran once in `generate.sh`, and their output
is committed under `generated/`. Kiota and Swagger Codegen clients each made a first call against
the stand-in in that run, with their gems installed, and are inspected here without them.
Kiota 1.38.0 ran only `kiota info`. sdkgen 4.45.0 generated an identical `rb/` tree. OpenAPI
Generator was not run; its `library` option comes from its documentation. The Faraday client in
`handwritten/` ran once against the stand-in, with Faraday 2.15.1, outside the gate.

[^1]: The generated `gemspec` summary calls the gem an "Unofficial generated Ruby SDK for the
Bookshelf public API", not affiliated with or endorsed by the upstream API provider. The sentence
comes from `pkgDescription` in sdkgen's
[`packageMeta.ts`](https://unpkg.com/@voxgig/sdkgen@4.44.3/src/helpers/packageMeta.ts), which
writes the same disclaimer, with the language swapped, into this project's TypeScript and Python
manifests, whoever owns the API.

[^2]: The Kiota [changelog](https://github.com/microsoft/kiota/blob/main/CHANGELOG.md) entry for
1.39.0, dated 2026-11-17, lists "Ruby is now a preview language" among its changes. Kiota 1.38.0's `kiota info`
reported Ruby's maturity as Experimental for the same document. The
[overview](https://learn.microsoft.com/en-us/openapi/kiota/overview) lists Ruby among its seven
languages and gives none of them a grade.