Scala Spray+Swagger , how to auto-generate UI for API calls

Question

Working on a project and using Spray

Want to add Swagger to get a nice UI for all the calls

Found :

• http://github.com/gettyimages/spray-swagger

Problem is I cant seem to get it to work with my project, with no docs or

run examples its like walking in the dark .... (and time consuming)

did any 1 get to work with this and has a

• test example
• wiki page
• any thing helpful

So i can get get it working?

Thanks!

Answer 1

the project has been updated with a wiki and usage information!

This looks promising :

https://github.com/gettyimages/spray-swagger

didn't try it out yet but looking good!

Answer 2

So I took a stab at this and got it working. You can check out my repo here.

Granted, it is my scratchpad for exploring Spray, so some things may change. Also, this is based on Spray 1.3.0.

The general gist of getting this to work, as I understand it, is:

1. You have your traits/classes that hold your routes; lets call this a "Resource". Each one of these traits/classes roughly corresponds to a "path" (e.g. /posts)
2. In your Resources, instead of directly using the Spray DSL to construct one big route, you need to have one method for each endpoint(roughly corresponding to an "action" in Rails controller, or a route in Sinatra/Scalatra). These methods need to be annotated. So for example you would have separate def postCreate, def postDeletes, etc. These would then need to be composed separately for your Resource.
3. You instantiate a SwaggerHttpService, implementing the necessary methods (including a Sequence of all the traits/classes in 1, and a Sequence of all your ApiModels that are used in your annotations).
4. The combination of all your routes (across your actual API and the SwaggerHttpService) needs to get passed to your central routing actor's receive method wrapped in a runRoute (this is the actor that gets in Boot.scala)

I believe 1. and 2. are necessary because spray-swagger works with Java annotations, which cannot be retrieved when wrapped inside an opaque function (which is what the Spray routing DSL normally composes for you).

Answer 3

One of my concerns spray-swagger is that the annotations make the code harder to read. Any ideas for how to make the code readable & still get the benefits of Swagger?

    @Api(value = "/pet", description = "Operations about pets")
trait PetHttpService extends HttpService {

  @ApiOperation(httpMethod = "GET", response = classOf[Pet], value = "Returns a pet based on ID")
  @ApiImplicitParams(Array(
      new ApiImplicitParam(name = "petId", required = false, dataType = "integer", paramType = "path", value = "ID of pet that needs to be fetched")
        ))
  @ApiResponses(Array(
    new ApiResponse(code = 400, message = "Invalid ID Supplied"),
    new ApiResponse(code = 404, message = "Pet not found")))
  def petGetRoute = get { path("pet" / IntNumber) { petId =>
    complete(s"Hello, I'm pet ${petId}!")
    } }
}

I'm going to create a trait with annotations & extend to see if the annotations work. Will let you guys know what happens!