Open API Game: Swagger Play

1. Cara mempercepat versi terbaru Swagger-Play (modul Play yang memungkinkan Anda untuk menggunakan anotasi swagger-api dan menghasilkan dokumentasi berdasarkan spesifikasi OpenAPI) dan cara mengonfigurasi swagger-ui (perpustakaan javascript yang digunakan untuk memvisualisasikan dokumentasi yang dihasilkan)
2. Saya akan menjelaskan anotasi utama dari Swagger-Core dan berbicara tentang fitur penggunaannya untuk Scala
3. Saya akan memberi tahu Anda cara bekerja dengan kelas model data dengan benar
4. Bagaimana menyiasati masalah tipe generik di Swagger, yang tidak tahu cara bekerja dengan obat generik
5. Cara mengajar Swagger untuk memahami ADT (tipe data aljabar)
6. Cara mendeskripsikan koleksi

Tambahkan ketergantungan

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)

Anotasi

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

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

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

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

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

Koleksi

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

Kesimpulan