Openapi

At build-time, when encountering a service annotated with the alloy#simpleRestJson protocol, Smithy4s will automatically generate an openapi "view" for this service.

namespace smithy4s.example

use alloy#simpleRestJson

@simpleRestJson
service HelloWorldService {
  version: "1.0.0"
  operations: [Hello]
}

The smithy4s-http4s-swagger module provides a one liner function to serve swagger-ui using that generated openapi view. By default, the documentation is routed under the /docs path.

In build.sbt

libraryDependencies ++= Seq(
  // version sourced from the plugin
  "com.disneystreaming.smithy4s"  %% "smithy4s-http4s-swagger" % smithy4sVersion.value
)

In Docs.scala, create an instance of the documentation HttpRoutes. There are multiple ways to do that. Pick the one you need:

import org.http4s._
import cats.effect.IO
// the package under which the scala code was generated
import smithy4s.example.hello._

object Docs {
  //simplest
  val myDocRoutes: HttpRoutes[IO] =
    smithy4s.http4s.swagger.docs[IO](HelloWorldService)

  // documentation served at /custom-docs
  val customPath: HttpRoutes[IO] =
    smithy4s.http4s.swagger.docs.withPath("custom-docs")(HelloWorldService)

  // documentation served at /docs with multiple service specification defined.
  val multipleServices: HttpRoutes[IO] =
    smithy4s.http4s.swagger.docs[IO](HelloWorldService, HelloWorldService)

  // documentation served at /custom-docs with swagger assets from `/swagger-ui-path`
  // (from the classpath) being used.
  val customSetup =
     smithy4s.http4s.swagger.docs[IO]
      .withPath("custom-docs")
      .withSwaggerUiResources("/META-INF/custom-swagger-ui")(HelloWorldService)
}

As a reminder, http4s' HttpRoutes can be composed using the <+> operator

import smithy4s.http4s._
import smithy4s.http4s.swagger.docs
import cats.effect.IO
import cats.implicits._
import org.http4s.implicits._
import smithy4s.example.hello._

// ...
val docRoutes = docs[IO](HelloWorldService)
val app = SimpleRestJsonBuilder
  .routes(HelloWorldImpl)
  .make
  .map(serviceRoutes => docRoutes <+> serviceRoutes)
  .map(_.orNotFound)

Swagger UI

When you visit your documentation page, you'll be served with a Swagger UI application that looks like this:

If your documentation route supports multiple service, the dropdown in the top bar (top right) should allow you to select other specifications: