swagger-integration.md

Swagger integration

We have a swagger integration so that users can explore the server API through swagger-ui.

Some highlights:

• We are using tapir which integrates an open-api module for swagger.
• Swagger-ui is exposed locally at http://localhost:9000/docs.
• Be sure to check existing endpoints to see real examples.
• Option[T] values are supported, sending a json without the key and value will be interpreted as None, otherwise, Some(value) will be sent.

Creating an endpoint definition

We have to define our endpoints at the endpoints package, for example:

val basicPostEndpoint = endpoint
  .post("basic") // points to POST http://localhost:9000/basic
  .tag("Misc") // tags the endpoint as "Misc" on swagger-ui
  .in(
    jsonBody[Basic.Request].example( // expects a JSON body of type BasicGet.Request with example values
      BasicGet.Request(
        name = "Alexis",
        email = "alexis@wiringbits.net"
      )
    )
  )
  .out(
    jsonBody[Basic.Response].example( // returns a JSON body of type BasicGet.Response with example values
      BasicGet.Response(
        message = "Hello Alexis!"
      )
    )
  )

Api models must have an implicit Schema defined, for example:

Schema
  .derived[Response]
  .name(Schema.SName("BasicResponse"))
  .description("Says hello to the user")

And then integrate the endpoint to the ApiRouter file:

object ApiRouter {
  private def routes(implicit ec: ExecutionContext): List[AnyEndpoint] = List(
    basicPostEndpoint
  )
}

Endpoint user authentication details

We use Play Session cookie for user authentication, this is a cookie that's stored securely and is sent on every request, this cookie is used to identify the user and to check if the user is authenticated.

Any endpoint that requieres user authentication must include our implicit userAuth handler and convert the endpoint val to def that receives an implicit handler implicit authHandler: ServerRequest => Future[UUID], for example:

def basicEndpoint(implicit authHandler: ServerRequest => Future[UUID]) = endpoint.get
  .in(userAuth)

For more information about creating endpoints, please check the tapir documentation.