From 7777abb3b83e6ba9f267c0c8c25576727e0dca60 Mon Sep 17 00:00:00 2001
From: Mladen Jablanovic <mladen.jablanovic@phrase.com>
Date: Wed, 23 Sep 2026 15:52:09 +0200
Subject: [PATCH] docs(ruby): generate valid Ruby in doc code samples

Model doc samples were not valid Ruby: unquoted strings, `null` for
missing examples, HTML-escaped arrays/hashes, a per-run `[B@...` value
for binary fields, and `require 'Phrase'` instead of the gem name.
Object params in API doc samples rendered as `{ ... }`.

- model_doc.mustache: require the gem name, quote strings, wrap
  timestamps in Time.parse, use File.new for binary fields, and render
  examples unescaped.
- Makefile: mustache can't tell a missing example ("null") from a real
  one, so rewrite those to `nil` (and `{ ... }` to `{}`) after
  generation.

Verified by parsing all 543 generated Ruby snippets with Prism: no
syntax errors, and every model sample argument is a literal.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Makefile                                                   | 3 +++
 openapi-generator/templates/ruby-client/model_doc.mustache | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 2976566bc..d04a6bbae 100644
--- a/Makefile
+++ b/Makefile
@@ -19,8 +19,11 @@ bundle:
 watch_bundle:
 	make lint
 	npx swagger-cli bundle -t json -w 300 main.yaml > doc/compiled.json
+# The generator renders missing examples as "null" and object params as "{ ... }",
+# which mustache can't detect; rewrite them so the doc code samples are valid Ruby.
 ruby:
 	openapi-generator-cli generate -i tmp/compiled.yaml -g ruby -o clients/ruby -c ./openapi-generator/ruby_lang.yaml
+	perl -pi -e "s/: (?:null|'null'|Time\.parse\('null'\))(?=[,)]\$$)/: nil/; s/\{ \.\.\. \}/{}/g" clients/ruby/docs/*.md
 go:
 	openapi-generator-cli generate -i tmp/compiled.yaml -g go -o clients/go -c ./openapi-generator/go_lang.yaml --global-property apiTests=false,modelTests=false
 	go install golang.org/x/tools/cmd/goimports@v0.24.0
diff --git a/openapi-generator/templates/ruby-client/model_doc.mustache b/openapi-generator/templates/ruby-client/model_doc.mustache
index 63cb29bd4..5cb256f29 100644
--- a/openapi-generator/templates/ruby-client/model_doc.mustache
+++ b/openapi-generator/templates/ruby-client/model_doc.mustache
@@ -10,9 +10,9 @@ Name | Type | Description | Notes
 ## Code Sample
 
 ```ruby
-require '{{moduleName}}'
+require '{{gemName}}'
 
-instance = {{moduleName}}::{{classname}}.new({{#vars}}{{name}}: {{#isBinary}}File.new('/path/to/file'){{/isBinary}}{{^isBinary}}{{example}}{{/isBinary}}{{^-last}},
+instance = {{moduleName}}::{{classname}}.new({{#vars}}{{name}}: {{#isBinary}}File.new('/path/to/file'){{/isBinary}}{{^isBinary}}{{#isString}}'{{{example}}}'{{/isString}}{{^isString}}{{#isDateTime}}Time.parse('{{{example}}}'){{/isDateTime}}{{^isDateTime}}{{{example}}}{{/isDateTime}}{{/isString}}{{/isBinary}}{{^-last}},
                                  {{/-last}}{{/vars}})
 ```