Jeu API ouvert: Swagger Play

1. Comment fixer la dernière version de Swagger-Play (module Play qui vous permet d'utiliser des annotations swagger-api et de générer de la documentation basée sur la spécification OpenAPI) et comment configurer swagger-ui (bibliothèque javascript utilisée pour visualiser la documentation générée)
2. Je vais décrire les principales annotations de Swagger-Core et parler des caractéristiques de leur utilisation pour Scala
3. Je vais vous expliquer comment travailler correctement avec des classes de modèle de données
4. Comment contourner le problème de type générique dans Swagger, qui ne sait pas comment travailler avec des génériques
5. Comment apprendre à Swagger à comprendre l'ADT (types de données algébriques)
6. Comment décrire les collections

Ajouter une dépendance

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)

Annotations

@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") ))

Exemple 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
                )

Exemple 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 =>

Exemple 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]
  )

Exemple 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"
    )
  ))

Les collections

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

Conclusion