Smithy SDK code generator for Ruby.
WARNING: All interfaces are subject to change.
Generating an SDK for a Rails JSON API
A full end-to-end demo for a Rails JSON API can be found in the example/ folder
- Install Smithy CLI
- Add your smithy model under
<project_root>/model
. - Create
a smithy-build.json
file that defines how Smithy should build your SDK. It must define a section
under
plugins
forruby-codegen
. It must also add a maven dependencies block and depend onsoftware.amazon.smithy.ruby:smithy-ruby-rails-codegen
. For reference see: rails json test smithy-build.json. - Run
smithy build
Instead of the Smithy CLI, you can instead create a gradle project. Doing so allows further customization of the build process if necessary, or implementing your own protocol.
- Create a new gradle project
- Add smithy to the plugins list (Note: you can find the latest plugin version at: https://plugins.gradle.org/plugin/software.amazon.smithy)
plugins {
id("software.amazon.smithy").version("0.6.0")
}
- Add the smithy-ruby-rails-codegen as a dependency:
dependencies {
implementation("software.amazon.smithy.ruby:smithy-ruby-rails-codegen:0.2.0")
}
- Add your smithy model under
<project_root>/model
. - Create
a smithy-build.json
file
that defines how Smithy should build your SDK. It must define a section
under
plugins
forruby-codegen
. For reference see: rails json test smithy-build.json. - Execute the gradle
build
task. This will generate the SDK from your model using the settings from your smithy-build.json file.
The generated SDK will be available under the build/smithyprojections/< project_name>//ruby-codegen folder.
For an overview of SDK features, see the wiki: https://github.com/smithy-lang/smithy-ruby/wiki
This project is licensed under the Apache-2.0 License.
See CONTRIBUTING for more information.
Many Gradle issues can be fixed by stopping the daemon by
running ./gradlew --stop
There is a top level Rakefile
that defines tasks for testing, checking style
and checking types for both Hearth and all parts of the codegen.
To run all checks and validations on all sub-projects run:
bundle exec rake
Or to run checks on the individual projects:
bundle exec rake check:hearth
bundle exex rake check:codegen
Java 17 is required to run gradle and the smithy/java based code generation.
The Rakefile
provides tasks for running code generation using gradle and it
will verify that the correct version of java is configured. To setup java,
either set the JAVA_HOME
on the environment or use jenv
to manage versions.
You will also need to run bundle install
from the top level directory.
Codegen integration tests are written as ruby rspec tests (under smithy-ruby-codegentest/integration-specs).
You can run all codegen integration tests with:
bundle exec rake codegen:build # runs build on codegen first
bundle exec rake test:white_label
Hearth has a full suite of rspec tests which can be run from the hearth
directory with: rspec
. Or by running bundle exec rake test:hearth
from the
top level directory.
The high_score_service
directory defines a rails service that can be run
with rails s
. You can then test manually by adding hearth and the generated
sdk client to your library path with:
irb -I 'hearth/lib' -I 'codegen/projections/high_score_service/lib'
And test with:
require 'high_score_service'
c = HighScoreService::Client.new(endpoint: 'http://127.0.0.1:3000')
c.get_high_score(id: '1')