Skip to main content

Quick Start

Below is a quick example of smithy4s in action. This page does not give very much explanation or detail. For more information on various aspects of smithy4s, read through the other sections of this documentation site.


Add the smithy4s-sbt-codegen plugin to your build.

addSbtPlugin("com.disneystreaming.smithy4s" % "smithy4s-sbt-codegen" % "0.14.2")


Enable the plugin in your project, add the smithy and http4s dependencies.

import smithy4s.codegen.Smithy4sCodegenPlugin

ThisBuild / scalaVersion := "2.13.8"

val example = project
libraryDependencies ++= Seq(
"com.disneystreaming.smithy4s" %% "smithy4s-http4s" % smithy4sVersion.value,
"com.disneystreaming.smithy4s" %% "smithy4s-http4s-swagger" % smithy4sVersion.value,
"org.http4s" %% "http4s-ember-server" % "0.23.14"


Define your API in smithy files.

namespace smithy4s.hello

use smithy4s.api#simpleRestJson

service HelloWorldService {
version: "1.0.0",
operations: [Hello]

@http(method: "POST", uri: "/{name}", code: 200)
operation Hello {
input: Person,
output: Greeting

structure Person {
name: String,

town: String

structure Greeting {
message: String

The Scala code corresponding to this smithy file will be generated the next time you compile your project.


Implement your service by extending the generated Service trait. Wire up routes into server.

import smithy4s.hello._
import cats.effect._
import cats.implicits._
import org.http4s.implicits._
import org.http4s.ember.server._
import org.http4s._
import smithy4s.http4s.SimpleRestJsonBuilder

object HelloWorldImpl extends HelloWorldService[IO] {
def hello(name: String, town: Option[String]) : IO[Greeting] = IO.pure {
town match {
case None => Greeting(s"Hello $name!")
case Some(t) => Greeting(s"Hello $name from $t!")

object Routes {
private val example: Resource[IO, HttpRoutes[IO]] =

private val docs: HttpRoutes[IO] =[IO](HelloWorldService)

val all: Resource[IO, HttpRoutes[IO]] = <+> docs)

object Main extends IOApp.Simple {

val run = Routes.all
.flatMap { routes =>
.use(_ => IO.never)


Run Service

sbt "example/run"

Here you will find the automatically generated SwaggerUI which will allow you to easily test your API.

SwaggerUI documentation site request

SwaggerUI documentation site response

Client Example

You can also generate a client using smithy4s.

import org.http4s.ember.client.EmberClientBuilder

object ClientImpl extends IOApp.Simple {

val helloWorldClient: Resource[IO, HelloWorldService[IO]] = for {
client <- EmberClientBuilder.default[IO].build
helloClient <- SimpleRestJsonBuilder(HelloWorldService).clientResource(
} yield helloClient

val run = helloWorldClient.use(c =>
c.hello("Sam", Some("New York City"))
.flatMap(greeting => IO.println(greeting.message))