Creating Smithy Projects with Smithy Init

The Smithy team is excited to announce the release of the init command in Smithy CLI. This command enables developers to create new Smithy projects quickly and easily.

Before the Smithy init command was introduced, developers had to carefully follow along with a developer guide or blog post to setup their Smithy projects. This involves copying and pasting code snippets, as well as creating various files and directories. With the introduction of the init command, developers can use a single command to create a project with all the necessary Smithy files, configuration files, and directories, all tailored to their use case. The new init command simplifies developer experience of getting started with Smithy, and it is less error-prone as it creates projects based on templates. The templates provided by the init command cater to different project needs as well as to serve as great examples. Developers can use these templates to explore different project setups and learn about various Smithy features.

What is Smithy?

Smithy is an open-source Interface Definition Language (IDL) and set of tools for building web services, created by AWS. AWS uses Smithy to model services, generate server scaffolding, generate SDKs for multiple languages, and generate AWS SDKs. Smithy enables large-scale collaboration on API’s through its extensible meta-model and pluggable design. It is purpose-built to support code generation in multiple languages, enables automatic API standards enforcement, and is protocol-agnostic. Smithy’s design is rooted in our experience from building thousands of service APIs and developing complex SDKs within Amazon. To learn more, check out the smithy.io website, and please watch the introductory talk from one of Smithy’s creators.

What is the Smithy CLI?

The Smithy CLI allows developers to quickly iterate on their Smithy models. Using the Smithy CLI, developers can quickly initialize a Smithy project, build models, run validation, compare models for differences, query models, and more. The Smithy CLI is available to download on macOS, Linux, and Windows platforms.

Getting Started

If you haven’t installed the Smithy CLI before, follow the installation guide. If you have installed the Smithy CLI, run smithy --version in a terminal to verify that the version is 1.36.0 or above. If Homebrew was used to install the Smithy CLI, you can update it to the latest version by running brew upgrade smithy-cli in a terminal. Otherwise, please refer to the installation guide to update.

With the Smithy CLI installed, you can view the help information for the init command by using the --help flag:

$ smithy init --help
Usage: smithy init [--help | -h] [--debug] 
                   [--quiet] [--no-color] 
                   [--force-color] [--stacktrace] 
                   [--logging LOG_LEVEL] 
                   [--template | -t quickstart-cli] 
                   [--url https://github.com/smithy-lang/smithy-examples.git] 
                   [--output | -o new-smithy-project] 
                   [--list | -l] 
Initialize a smithy project using a template

Next, we will demonstrate how the init command can be used to create a new Smithy project.

Create a new Smithy project

Let’s create a new project by calling the init command:

$ smithy init --output ./new-smithy-project
Smithy project created in directory: new-smithy-project

This will create a new project in the new-smithy-project directory:

$ tree ./new-smithy-project
./new-smithy-project
├── README.md
├── models
│   └── weather.smithy
└── smithy-build.json

By default, the init command line tool will create a new project using the quickstart-cli template. In the following section, we will view the available templates and how to access them.

Utilizing project templates

The init command offers a selection of project templates catering to different needs. Each template has its own smithy-build.json file and model files for serving different project needs. This is useful if you are new to Smithy and want to learn about different Smithy features. For example, you may want to use a template to create a project consisting a simple service modeled in Smithy.

To view the available templates and their respective use cases, you can run the init command with the --list flag:

$ smithy init --list   
────────────────────────────  ──────────────────────────────────────────────────────────────────────
NAME                          DOCUMENTATION
────────────────────────────  ──────────────────────────────────────────────────────────────────────
common-linting-configuration  Gradle project to create a package to define a common set of model
                              validations.
custom-annotation-trait       Gradle project for creating a package for a custom annotation trait.
custom-linter                 Gradle project to create a custom, configurable model linter.
custom-string-trait           Gradle project for creating a package for a custom string trait.
custom-structure-trait        Gradle project for creating a package for a custom structure trait.
custom-validator              Gradle project to create a custom model validator.
decorators                    Gradle project to create a custom  decorator for validation events.
filter-internal-projection    Projection that filters out internal shapes and traits.
quickstart-cli                Smithy Quick Start example weather service using the Smithy CLI.
quickstart-gradle             Smithy Quick Start example weather service using the
                              Smithy-Gradle-Plugin.
shared-model-package          Gradle project to create a shared package of common Smithy models.
smithy-to-openapi             Generate an OpenAPI spec from a Smithy model

Let’s try using the quickstart-gradle template to create a project for a weather service. You can call the init command using the --template flag:

$ smithy init --template quickstart-gradle --output ./my-new-service
Smithy project created in directory: my-new-service

This will create a project consisting of the Smithy model file, the smithy-build.json file and various Gradle config files within the my-new-service directory:

$ tree ./my-new-service
./my-new-service
├── README.md
├── build.gradle.kts
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties
├── gradlew
├── gradlew.bat
├── models
│   └── weather.smithy
├── settings.gradle.kts
└── smithy-build.json

As you can see, the init command simplifies the initiation of a new Smithy project. We encourage you to try out the other templates to learn more about different project setups and Smithy features!

Templates repository

Behind the scenes, the init command checks the latest list of templates available from Smithy’s smithy-examples Git repository. This open-source repository includes contributions from both AWS and community members.

Developers have the flexibility to override the default repository with an alternative one. Developers may want to set up their own template repository to share Smithy models specific to their products or use case. Alternatively, they may want to create a set of private templates to be shared within an organization.

The --url parameter specifies a custom repository:

$ smithy init --template some-common-package --url https://github.com/user/repo.git
Smithy project created in directory: some-common-package

The init command expects a smithy-templates.json file at the root level of the repository. Here is an example from smithy-examples repository for reference.

What’s Next?

With the Smithy init command now available, developers can quickly and easily initiate Smithy projects from a set of curated project templates. Developers can also utilize the templates to explore different project setups and learn about various Smithy features.

We encourage you to try out the Smithy init command and tell us your thoughts by contacting us on GitHub. Please don’t hesitate to create an issue or a pull request if you have ideas for improvements.

About the author: