Home

Awesome

Smithy Ruby

Smithy SDK code generator for Ruby.

WARNING: All interfaces are subject to change.

License

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

Using Smithy CLI (recommended)

  1. Install Smithy CLI
  2. Add your smithy model under <project_root>/model.
  3. Create a smithy-build.json file that defines how Smithy should build your SDK. It must define a section under plugins for ruby-codegen. It must also add a maven dependencies block and depend on software.amazon.smithy.ruby:smithy-ruby-rails-codegen. For reference see: rails json test smithy-build.json.
  4. Run smithy build

Using Gradle

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.

  1. Create a new gradle project
  2. 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")
}
  1. Add the smithy-ruby-rails-codegen as a dependency:
dependencies {
    implementation("software.amazon.smithy.ruby:smithy-ruby-rails-codegen:0.2.0")
}
  1. Add your smithy model under <project_root>/model.
  2. Create a smithy-build.json file that defines how Smithy should build your SDK. It must define a section under plugins for ruby-codegen. For reference see: rails json test smithy-build.json.
  3. 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>/<service-name>/ruby-codegen folder.

Using the SDK

For an overview of SDK features, see the wiki: https://github.com/smithy-lang/smithy-ruby/wiki

License

This project is licensed under the Apache-2.0 License.

Security

See CONTRIBUTING for more information.

Troubleshooting

Many Gradle issues can be fixed by stopping the daemon by running ./gradlew --stop

Testing

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

Setup/Dependencies

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.

Running codegen integration tests

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

Running hearth unit tests.

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.

Manual Testing

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')