How-to › Ship an SDK

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.

Audience
Library maintainer
Level
intermediate
Topic
Target another language
Languages
Ruby
Verified

Your SDK ships TypeScript, Python and Go, and a customer asks for Ruby. The generated gem loads, but its calls read like a port, client.Book.load({ "id" => "b2" }), and its version says 0.0.1 while the other three say 1.4.0. Nothing in CI shows it sends the requests the others send, and Ruby reports a renamed method only when a caller hits it.

What you get

You will end up with a Ruby gem on the same version as your other targets, a keyword-argument facade that survives regeneration, and one corpus that both clients pass. This is for you if you maintain a generated SDK and Ruby is the next language.

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, 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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written Faraday clientOne API, few operations, and Ruby callers who expect keyword arguments and StructsEvery operation and field written by hand, and a field the API adds is dropped until you add itThe API changes often, or you ship it in four languages
KiotaYou already run Kiota for other languages and want the same request-builder shape in RubyNo gemspec, six runtime gems in its quickstart, and a Ruby target its own release labels previewYou need a publishable gem out of the generator
OpenAPI Generator ruby generator, faraday libraryYou run OpenAPI Generator for other languages and want the Ruby gem on FaradayTyphoeus by default, so the faraday library must be chosen, and a template set per language to customizeYou want one model for every target
sdkgen rb targetAn sdkgen project whose other targets should share the Ruby gem’s model, features and versionSymbol keys in a data hash dropped unsent, no VERSION constant, and require_paths of ., so a facade does the Ruby partRuby is your only language, or idiom matters more than parity
Swagger CodegenYou want a conventional gem, lib/ and a VERSION constant, from one config fileTyphoeus underneath, so the system’s libcurl too, and an options hash on every callThe 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/:

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 names the key, main.kit.target.<t>.publish.version, one per target, so a lockstep release sets all four:

# 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'
node versions.mjs
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:

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.

node corpus.mjs
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 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 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.

ruby inspect.rb
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.

node --test ruby-target.test.mjs
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.

node pitfall.mjs
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.

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.

Footnotes

  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, which writes the same disclaimer, with the language swapped, into this project’s TypeScript and Python manifests, whoever owns the API. ↩︎ Back to text

  2. The Kiota changelog 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 lists Ruby among its seven languages and gives none of them a grade. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.