Offenes API-Spiel: Swagger Play

1. So befestigen Sie die neueste Version von Swagger-Play (Play-Modul, mit dem Sie Swagger-API-Annotationen verwenden und Dokumentation basierend auf der OpenAPI-Spezifikation erstellen können) und wie konfigurieren Sie Swagger-UI (Javascript-Bibliothek zur Visualisierung der generierten Dokumentation)
2. Ich werde die Hauptanmerkungen von Swagger-Core beschreiben und über die Funktionen ihrer Verwendung für Scala sprechen
3. Ich werde Ihnen erklären, wie Sie mit Datenmodellklassen richtig arbeiten
4. Wie man das generische Typproblem in Swagger umgeht, das nicht weiß, wie man mit Generika arbeitet
5. Wie man Swagger beibringt, ADT (algebraische Datentypen) zu verstehen
6. Wie man Sammlungen beschreibt

Abhängigkeit hinzufügen

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)

Anmerkungen

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

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

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

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

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

Sammlungen

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

Fazit