AWS Developer Tools Blog
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:
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:
This will create a new project in the new-smithy-project
directory:
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:
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:
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:
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:
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: