Juego de API abierta: Swagger Play

1. Cómo fijar la última versión de Swagger-Play (módulo Play que le permite usar anotaciones swagger-api y generar documentación basada en la especificación OpenAPI) y cómo configurar swagger-ui (biblioteca javascript utilizada para visualizar la documentación generada)
2. Describiré las principales anotaciones de Swagger-Core y hablaré sobre las características de su uso para Scala
3. Te diré cómo trabajar correctamente con las clases de modelo de datos.
4. Cómo solucionar el problema del tipo genérico en Swagger, que no sabe cómo trabajar con genéricos
5. Cómo enseñar a Swagger a comprender ADT (tipos de datos algebraicos)
6. Cómo describir colecciones

Agregar dependencia

libraryDependencies ++= Seq(
  "io.swagger" %% "swagger-play2" % "2.0.1-SNAPSHOT"
)

libraryDependencies ++= Seq(
  "com.iterable" %% "swagger-play" % "2.0.1"
)

resolvers += Resolver.sonatypeRepo("releases")

play.modules.enabled += "play.modules.swagger.SwaggerModule"

GET     /swagger.json           controllers.ApiHelpController.getResources

libraryDependencies += "org.webjars" % "swagger-ui" % "3.25.3"

def redirectDocs: Action[AnyContent] = Action {
    Redirect(
       url = "/assets/lib/swagger-ui/index.html",
       queryStringParams = Map("url" -> Seq("/swagger.json")))
  }

GET   /docs                   controllers.HomeController.redirectDocs()

libraryDependencies +=  "org.webjars" %% "webjars-play" % "2.8.0"

GET     /assets/*file               controllers.Assets.at(path="/public", file)

Anotaciones

@Api(value = «RestController», produces = «application/json»)
class RestController @Inject()(

@ApiResponses(value = {
      @ApiResponse(code = 400, message = "Invalid ID supplied"),
      @ApiResponse(code = 404, message = "Pet not found") })

@ApiResponses(value = Array(
      new ApiResponse(code = 400, message = "Invalid ID supplied"),
      new ApiResponse(code = 404, message = "Pet not found") ))

Ejemplo 1

def find(id: String): Action[AnyContent] = 
    safeAction(AllowRead(DrillObj)).async { implicit request =>
      drillsDao.findById(UUID.fromString(id))
        .map(x => x.fold(NotFound(s"Drill with id=$id not found"))(x => 
            Ok(write(x)))).recover(errorsPf)
    }      

 @ApiOperation(
    value = " ",
    response = classOf[Drill]
  )
  @ApiResponses(value = Array(
    new ApiResponse(code = 404, message = "Drill with id=$id not found")
  ))
  def find(@ApiParam(value = "String rep of UUID, id ") id: String)=
    safeAction(AllowRead(DrillObj)).async { implicit request =>
      drillsDao.findById(UUID.fromString(id))
        .map(x => x.fold(NotFound(s"Drill with id=$id not found"))(x =>
          Ok(write(x)))).recover(errorsPf)
    }

@ApiModel
case class Drill(
                id: UUID,
                name: String,
                @ApiModelProperty(
                  dataType = "Long",
                  example = "1585818000000"
                )
                start: Instant,
                @ApiModelProperty(
                  dataType = "Long",
                  example = "1585904400000"
                )
                end: Option[Instant],
                isActive: Boolean
                )

Ejemplo 2

 @ApiOperation(value = " ")
  @ApiImplicitParams(Array(
    new ApiImplicitParam(
      value = " ",
      required = true,
      dataTypeClass = classOf[Drill],
      paramType = "body"
    )
  ))
  @ApiResponses(value = Array(
    new ApiResponse(code = 200, message = "ok")
  ))
  def insert() = safeAction(AllowWrite(DrillObj)).async { implicit request =>

Ejemplo 3

case class SessionedResponse[T](
                            val ses: SessionData,
                            val payload: T
                          )

@ApiOperation(
    value = " ",
    response = classOf[SessionedResponse[Drill]]
  )

class SessionedResponse[T](
                            val ses: SessionData,
                            val payload: T
                          )

object SessionedResponse {
  def apply[T](ses: SessionData, payload: T) = new SessionedResponse[T](ses, payload)
 
}

private[controllers] class DrillSessionedResponse(
          ses: SessionData,
          payload: List[Drill]
) extends SessionedResponse[List[Drill]](ses, payload)

@ApiOperation(
    value = " ",
    response = classOf[DrillSessionedResponse]
  )

Ejemplo 4

sealed trait Permission

case class Write(obj: Obj) extends Permission
case class Read(obj: Obj) extends Permission

//  permission.drill
case object DrillObj extends Obj

// permission.team
case object TeamObj extends Obj

@ApiModel(value = "Permission")
case class FakePermission(
       @ApiModelProperty(
         name = "$type",
         allowableValues = "ru.myproject.shared.Read, ru.myproject.shared.Read"
       )
       t: String,
       @ApiModelProperty(allowableValues = "permission.drill, permission.team"
       obj: String
     )

@ApiImplicitParams(Array(
    new ApiImplicitParam(
      value = "",
      required = true,
      dataTypeClass = classOf[FakePermission],
      paramType = "body"
    )
  ))

Colecciones

dataType = "List[ru.myproject.shared.roles.FakePermission]"

Conclusión