Support Swagger 2.x annotations

[gaeljw]

Hello

This just an issue to track the fact that I've seen in the README:

We also would like to support Swagger 2.0 in the future and contributions to that end will be gladly accepted.

I may try to give it a shot in the coming weeks

[dwickern]

The main component to rewrite would be PlayReader. There's also a dependency on swagger-scala-module to be in-sourced and rewritten for swagger-core 2.x.

If we're doing a rewrite, I have a bigger vision that would solve some pain points I've dealt with:

• Option[T] requires @ApiModelProperty(dataType = "...") annotation due to type erasure
• AnyVal requires @ApiModelProperty(dataType = "...") annotation everywhere it's used. No way to specify that all usages of UserId(value: Int) extends AnyVal are { "type": "integer" }
• scala.Enumeration requires @ApiModelProperty(dataType = "fully.qualified.path.to.MyEnum$") annotation, probably also due to type erasure
• Hiding APIs require strange @(ApiModelProperty @field @getter)(hidden = true) annotation in order to hide both the fields and getters from Jackson's reflection
• Easy to expose private APIs I didn't intend to expose, because Jackson reflection will follow the whole dependency graph
• Difficult to customize through trial and error. I've had to add bean-style getters to my traits/case classes in order to generate the correct JSON Schema

Instead of @ApiModel, we would use a Schema[T] type class for JSON Schema definitions:

case class User(id: Int, name: String)
object User {
  implicit val format: OFormat[User] = Json.format

  // This macro would generate a JSON schema matching the semantics of play-json's format macro.
  // You can customize the resulting schema or write a schema by hand for more complex cases.
  // The macro could support reading swagger-annotations for backwards compatibility.
  implicit val schema: Schema[User] = Schema.derived
}

And then we generate the OpenAPI routes from Play's router:

// conf/routes
GET /api/users/:id     controllers.UserController.getById(id: Int)

// target/generated.scala
class GeneratedRouteInfo {
  val controllers_UserController_getById = Route(
    // all the information from the route file
    operationId = "getById",
    method = "GET",
    url = "/api/users/{id}",
    params = Seq(implicitly[Schema[Int]]),
  ).withDerived(
    // Use a macro to grab any additional information from the controller method, e.g. swagger-annotations
    Route.deriveMacro[controllers.UserController](_.getById)
  )
  // ... other routes

  val routes: Seq[Route] = Seq(
    controllers_UserController_getById,
    // ...other routes
  )
  val openAPI: OpenAPI = OpenAPI(routes)
}

From there we could output our preference of OpenAPI v2 or v3

[gaeljw]

What you say totally makes sense to me. Thanks for sharing.

I'm also a user of Tapir and I was considering building something in-between the Swagger Java annotations and Tapir. Your proposal goes in this direction.

I was also wondering if maybe all of this could be part of Play core, or at least moved under the playframework organization. I guess this would be something to discuss with them once we've got something working.

This sounds like quite some work but I'd be happy to help on this. I'll spend some time understanding a bit more the existing codebase and how to interact with the generated Play router.

[dwickern]

I got something started in https://github.com/dwickern/play-openapi

Here's a tour:

play-jsonschema

The project provides Schema[T] with implicit instances for play-json's default formats.

Schema[T] represents the JSON schema for type T. It's not concerned with parsing or validation. It's up to the user to define a Format[T] and Schema[T] that agree (and there are good reasons why they sometimes won't).

Schema.derived[T] derives case class instances, optionally annotated with Schema.annotations or swagger 1.x annotations (@ApiModel, @ApiModelProperty). You can look at SchemaTest.scala for usage examples.

play-openapi

The project provides provides a collection of APIs to build the OpenAPI spec.

A macro can derive swagger 1.x annotations (@Api, @ApiOperation, etc). Test suite SwaggerAnnotationsTest.scala

example

A sample Play project with basic CRUD APIs implemented two ways:

• SwaggerController.scala uses swagger 1.x annotations, where the OpenAPI spec is derived by macro

• OperationController.scala uses my half-baked attempt at a native syntax without macros

The native syntax abuses the way Play invokes controller.action(args*), which is equivalent to controller.action.apply(args*). And so these are equivalent actions:

class Controller {
  // normal controller action
  def action(arg1: Int, arg2: String): Action = ??? // the action body

  // controller action exposing OpenAPI metadata
  object action {
    def spec: Operation[?] = ??? // expose the OpenAPI spec associated with the action here
    def apply(arg1: Int, arg2: String): Action = ??? // the action body
  }
}

sbt plugin

Play Framework's Action signature carries very little information

class Controller {
  def action(arg1: Int, arg2: String): Action = ???
}

• We know there are 2 parameters and their types
• We don't know if they are path or query parameters, or one of each
• We don't know if query parameters are required or optional (there could be a default value in the routes file)
• We don't know the parameter names (the method doesn't have to match the parameter name in the routes file)
• We don't know the URL or HTTP verb
• We don't know anything about the request body, responses, headers, etc

PlayOpenApiPlugin.scala generates a catalog of all actions based on the routes file, sets the URL, HTTP verb and parameter information for each operation:

class GeneratedRouteInfo @javax.inject.Inject() (/* injected controllers */) {

  private val controllers_SwaggerController_updateUser9 = Operation.fromAction(SwaggerController_2.updateUser(_: Int))
    .path("/swagger/users/{id}")
    .verb(HttpVerb.PUT)
    .updateParam[Int](0, _.inPath.required.name("id"))

  val openApi: OpenApi = OpenApi.empty
    .operation(controllers_SwaggerController_updateUser9)
    .operation(/* the rest */)
}

TODOs

• implement $ref to deduplicate repeated schemas (also a prerequisite for recursive types)
• implement oneOf/discriminated schemas for sealed traits
• figure out what else is missing or could be improved
• move sbt plugin to its own project so it can be published
• various chores: set up CI, publishing, README, etc

I would appreciate the help! And I'd be happy to transfer it to the playframework org if they will have it

[gaeljw]

Wow I wasn't expecting that much that fast :) Look's really nice!

---

Not sure if that's the best place or if we should move discussions in the other repo (https://github.com/dwickern/play-openapi) but a few comments on top of my head:

It's up to the user to define a Format[T] and Schema[T] that agree (and there are good reasons why they sometimes won't).

I'm fine with this design, it's the same in Tapir, but I actually never really understood why they could differ sometimes. Do you have an example maybe? 🤔

OperationController.scala uses my half-baked attempt at a native syntax without macros

Interesting! At first, I felt like it forces the user to duplicate a lot of things (in the spec and in the actual Action) but not much more than with the regular Swagger annotations.

A macro can derive swagger 1.x annotations

I guess the idea would be to get the whole thing working for 1.x annotations first, and then we can expand to 2.x, right?

---

I would appreciate the help!

I only have a couple of hours per week right now but I'd be happy to help. Is there a specific part you'd like me to spend some time on? I like CI, publish setup and README but this can probably wait a bit.