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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hand-written Faraday client | 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 | 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 | 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 | 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 | 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/:
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.
Related how-tos
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
-
The generated
gemspecsummary 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 frompkgDescriptionin sdkgen’spackageMeta.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 -
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 inforeported 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