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.
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
$ 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
$ smithy init --output ./new-smithy-project Smithy project created in directory: new-smithy-project
This will create a new project in the
$ 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
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
$ 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
$ 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
$ 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!
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.
--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
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.
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: