Tapir extension to simplify creating error outputs for sealed traits

Extension library for Tapir that allows creating an EndpointOutput for a certain error type with multiple errors per status-code.

endpoint.get
  .in("v1" / "users" / path[String]("id"))
  .out(stringBody)
  .errorOut(anyOf[UserNotFound, WrongPassword, WrongUser])

See generated OpenApi

paths:
  /v1/users/{id}:
    get:
      operationId: getV1UsersId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            text/plain:
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/WrongPassword'
                - $ref: '#/components/schemas/WrongUser'
                discriminator:
                  propertyName: error
                  mapping:
                    wrong-password: '#/components/schemas/WrongPassword'
                    wrong-user: '#/components/schemas/WrongUser'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserNotFound'
components:
  schemas:
    UserNotFound:
      required:
      - name
      - error
      type: object
      properties:
        name:
          type: string
        error:
          type: string
          enum:
          - user-not-found
    WrongPassword:
      required:
      - id
      - error
      type: object
      properties:
        id:
          type: string
        error:
          type: string
          enum:
          - wrong-password
    WrongUser:
      required:
      - id
      - error
      type: object
      properties:
        id:
          type: string
        error:
          type: string
          enum:
          - wrong-user

Installation

Add the following line to your build.sbt file:

libraryDependencies += "com.alejandrohdezma" %% "tapir-anyof" % "2.0.0")

Usage

In order to use this library you need to follow these simple steps:

Create your error AST

First create your error as you would normally do using Tapir:

import io.circe.generic.extras.Configuration
import io.circe.generic.extras.ConfiguredJsonCodec

@ConfiguredJsonCodec sealed trait MyError
case class UserNotFound(name: String) extends MyError
case class WrongUser(id: String) extends MyError
case class WrongPassword(id: String) extends MyError

object MyError {

  implicit val config: Configuration =
    Configuration.default.withDiscriminator("error")

}

In this case we are using circe's Json, but you could use any available output type.

Provide `Schema` instances

Then you need to ensure that every error type has a Schema instance and that it is annotated with @code indicating the status code that should be used when that error is returned:

import com.alejandrohdezma.tapir._
import sttp.tapir.generic.auto._
import sttp.tapir.Schema
import io.circe.generic.extras.Configuration
import io.circe.generic.extras.ConfiguredJsonCodec
import sttp.model.StatusCode._

@ConfiguredJsonCodec sealed trait MyError
@code(NotFound) final case class UserNotFound(name: String) extends MyError
@code(Forbidden) final case class WrongUser(id: String) extends MyError
@code(Forbidden) final case class WrongPassword(id: String) extends MyError

object MyError {

  implicit val config: Configuration =
    Configuration.default.withDiscriminator("error")

  implicit lazy val MyErrorSchema: Schema[MyError] = Schema.derived[MyError]

}

Add discriminator information to `Schema`

Populate the sealed trait schema with the discriminator information by calling addDiscriminator indicating the discriminator name. This will involve two things: first, adding the actual discriminator value to the SCoproduct itself and second, adding the discriminator as a field to every subtype of the coproduct.

import com.alejandrohdezma.tapir._
import sttp.tapir.generic.auto._
import sttp.tapir.Schema
import io.circe.generic.extras.Configuration
import io.circe.generic.extras.ConfiguredJsonCodec
import sttp.model.StatusCode._

@ConfiguredJsonCodec sealed trait MyError
@code(NotFound) final case class UserNotFound(name: String) extends MyError
@code(Forbidden) final case class WrongUser(id: String) extends MyError
@code(Forbidden) final case class WrongPassword(id: String) extends MyError

object MyError {

  implicit val config: Configuration =
    Configuration.default.withDiscriminator("error")

  implicit lazy val MyErrorSchema: Schema[MyError] = Schema.derived[MyError].addDiscriminator("error")

}

Note: if using a different discriminator than the class simple-name (for example, kebab-case) you can add a second parameter to addDiscriminator that lets you modify the class simple-name:
implicit val config: Configuration =
  Configuration.default.withDiscriminator("error").withKebabCaseConstructorNames

implicit lazy val MyErrorSchema: Schema[MyError] =
  Schema.derived[MyError].addDiscriminator("error", config.transformConstructorNames)

Important: this method will fail with a runtime exception if used on a schema whose inner type is not a SCoproduct:

import com.alejandrohdezma.tapir._
import sttp.tapir.Schema

final case class SimpleError(name: String)

implicit val SimpleErrorSchema: Schema[SimpleError] = Schema.derived[SimpleError].addDiscriminator("error")
// java.lang.RuntimeException: Schema must be of type SCoproduct but schema is SProduct(List(SProductField(FieldName(name,name),Schema(SString(),None,false,None,None,None,None,false,false,All(List()),AttributeMap(Map())))))
// 	at scala.sys.package$.error(package.scala:27)
// 	at com.alejandrohdezma.tapir.package$SchemaDiscriminatorOps.addDiscriminatorAs(package.scala:93)
// 	at com.alejandrohdezma.tapir.package$SchemaDiscriminatorOps.addDiscriminator(package.scala:45)
// 	at repl.MdocSession$MdocApp3$$anonfun$31.apply$mcV$sp(README.md:139)
// 	at repl.MdocSession$MdocApp3$$anonfun$31.apply(README.md:135)
// 	at repl.MdocSession$MdocApp3$$anonfun$31.apply(README.md:135)

Create your `anyOf` utility

Anywhere in your code create an anyOf utility using AnyOf:

import sttp.tapir.json.circe.jsonBody

object anyOf extends AnyOf[MyError](jsonBody)

You don't necessarily have to use jsonBody, you can use any of the available output types.

Use it when creating your endpoint 🎉

import sttp.tapir._

val myEndpoint = endpoint.get
  .in("v1" / "users" / path[String]("id"))
  .out(stringBody)
  .errorOut(anyOf[UserNotFound, WrongUser, WrongPassword])

Important: remember that some of this utilities throw runtime exceptions, so you should ensure this won't fail on runtime by creating a simple test where you use the endpoint. If the anyOf call fails, the instantiation of the endpoint will fail.

See generated OpenApi

paths:
  /v1/users/{id}:
    get:
      operationId: getV1UsersId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            text/plain:
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/WrongPassword'
                - $ref: '#/components/schemas/WrongUser'
                discriminator:
                  propertyName: error
                  mapping:
                    wrong-password: '#/components/schemas/WrongPassword'
                    wrong-user: '#/components/schemas/WrongUser'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserNotFound'
components:
  schemas:
    UserNotFound:
      required:
      - name
      - error
      type: object
      properties:
        name:
          type: string
        error:
          type: string
          enum:
          - user-not-found
    WrongPassword:
      required:
      - id
      - error
      type: object
      properties:
        id:
          type: string
        error:
          type: string
          enum:
          - wrong-password
    WrongUser:
      required:
      - id
      - error
      type: object
      properties:
        id:
          type: string
        error:
          type: string
          enum:
          - wrong-user

alejandrohdezma/tapir-anyof

Tapir extension to simplify creating error outputs for sealed traits

Installation

Usage

Create your error AST

Provide `Schema` instances

Add discriminator information to `Schema`

Create your `anyOf` utility

Use it when creating your endpoint 🎉

On this page

Languages

Contributors

Latest Release

alejandrohdezma/tapir-anyof

Tapir extension to simplify creating error outputs for sealed traits

Installation

Usage

Create your error AST

Provide Schema instances

Add discriminator information to Schema

Create your anyOf utility

Use it when creating your endpoint 🎉

On this page

Languages

Contributors

Latest Release

Provide `Schema` instances

Add discriminator information to `Schema`

Create your `anyOf` utility