Resource definitions in Swagger about rho

[bryce-anderson]

This and issue #22 are things I wanted to address with MetaData. It should be pretty simple to make the functionality, the tricky part is to make it feel nice and not bring swagger specific stuff into rho proper.

[arouel]

I would say that our MetaData should hold a type that describes the resource entity. This is usually a case class that I would add as TypeTag.

Example Types for Swagger's pet store

GET /pet should be a Seq[Pet]
GET /pet/{id} should be a Pet
POST /pet should be a Seq[Pet]
PUT /pet should be a Seq[Pet]

Maybe we can use something like this?

object MyService extends RhoService with SwaggerSupport {
  GET / "pet" / "findByTags" +? param[String]("tags") ++ typeTag[Seq[Pet]] |>> { (tags: String) => "use a service to find pets by tags" }
  GET / "pet" / pathVar[Long]("id") ++ typeTag[Pet] |>> { (id: Long) => "use a service to find a pet by id" }
}

[bryce-anderson]

What you're doing describes the models which should be taken care of, though they will come back into play as we begin to require a status on the return, eg OK(cat: Pet). Do you want the comment, "use a service to find a pet by id"? That is what is missing from the swagger support.

[arouel]

I'm currently only interested to have a Data Type (and there subtypes) in my Swagger API documentation. So if I understood you correctly we can resolve this by using our new way to describe the response (e.g. OK(pets: Seq[Pet]), OK(pet: Pet)), right?

Ignore the string "use a service to find a pet by id" and think about a service call to get the pets ;-)

[bryce-anderson]

I'm not certain it works in the new way yet, I only have that to the point
of examining the syntax, but the old way should build models for you
automatically from collections and case classes. Check the example for a
case class model, but I haven't tested it first hand with collections.
(Good place for some tests!) I expect the shift to leave this unchanged.
On Aug 6, 2014 2:13 PM, "André Rouél" [email protected] wrote:

I'm currently only interested to have a Data Type (and there subtypes) in
my Swagger API documentation. So if I understood you correctly we can
resolve this by using our new way to describe the response (e.g. OK(pets:
Seq[Pet]), OK(pet: Pet)), right?

Ignore the string "use a service to find a pet by id" and think about a
service call to get the pets ;-)

—
Reply to this email directly or view it on GitHub
#21 (comment).

[arouel]

Sorry, maybe I missed something but in the Rho example for swagger is nothing that forms a DataType.

[bryce-anderson]

https://github.com/http4s/rho/blob/master/examples/src/main/scala/org/http4s/rho/swaggerdemo/Main.scala#L17
That builds a 'model' for you using reflection based on the return type of the route. I just discovered that the reflection isnt working right for types that have type parameters: I need to figure out how to get a TypeTag converted to a Manifest properly. That means its not working for List etc. I'm adding bug to this issue for that reason.

[arouel]

Thank you. Okay, I dig my nose in it. Maybe I can bring that further. FYI, I will use rho-swagger in the next weeks to find hard edges and cut them.

[bryce-anderson]

Little update, I don't think its worth the effort, or maybe even possible to convert a TypeTag to a Manifest properly. We may need to build our own machinery and quit relying on the json4s reflection until it operates on TypeTags.

[arouel]

Maybe we can have a chat about this if you have time.

[arouel]

We should think also about the following use case when it comes to the type definition of a response.

  GET / "pet" / id |>> { id: Int =>
    val found = for {
      pet <- businessLayer.findPet(id)
    } yield Ok(pet)
    found getOrElse NotFound(s"Pet $id not found.")
  }

With our existing implementation we cannot determine the data type automatically when explicitly handling different cases with different status codes and bodies.

So I assume it is better to define the data type in this case for Swagger explicitly.

[bryce-anderson]

I've thought about this myself and its an interesting question. I don't
know if its possible (without macros) to do it. The problem is a function
can only return one result, so each of the two examples you've shown are
different types, so scala will knock the result type down to the greatest
common denominator type. I would like to be able to have rho give a list of
the different result types, but I suspect that will require macros. I'm
actually not against that strategy, but I also don't know if it can be done
even with macros, and am pretty sure it will require a lot of work.

On Thu, Aug 21, 2014 at 1:42 PM, André Rouél [email protected]
wrote:

We should think also about the following use case when it comes to the
type definition of a response.

GET / "pet" / id |>> { id: Int =>
val found = for {
pet <- businessLayer.findPet(id)
} yield Ok(pet)
found getOrElse NotFound(s"Pet $id not found.")
}

With our existing implementation we cannot determine the data type
automatically when explicitly handling different cases with different
status codes and bodies.

So I assume it is better to define the data type in this case for Swagger
explicitly.

—
Reply to this email directly or view it on GitHub
#21 (comment).

[arouel]

Agree with you. Maybe we should think about to keep it very simplistic at first. I would say in the beginning we should only support the Response Class/Model in the success case when Status.Ok is in use. If I reduce it to that I come to the conclusion that Either (or something similar) can help us to determine the model. Usually I use in the non-successful case a case class Message.

What about this?

  GET / "pet" / id |>> { id: Int =>
    val found = for {
      pet <- businessLayer.findPet(id)
    } yield -\/(Ok(pet))
    found getOrElse \/-(NotFound(Message(s"Pet $id not found.")))
  }

I assume a scalaz.\/[NotFound[Message],Ok[Pet]] would help to handle it for Swagger.

[bryce-anderson]

Yes, that would help. The whole concept needs some work, as right now there
isn't support for the status type at all. That would be a good start here,
getting status codes built in. After that, the disjunction stuff would seem
relatively straight forward.

On Fri, Aug 22, 2014 at 3:22 PM, André Rouél [email protected]
wrote:

Agree with you. Maybe we should think about to keep it very simplistic at
first. I would say in the beginning we should only support the Response
Class/Model in the success case when Status.Ok is in use. If I reduce it
to that I come to the conclusion that Either (or something similar) can
help us to determine the model. Usually I use in the non-successful case a
case class Message.

What about this?

GET / "pet" / id |>> { id: Int =>
val found = for {
pet <- businessLayer.findPet(id)

} yield -\/(Ok(pet))
found getOrElse \/-(NotFound(Message(s"Pet $id not found.")))

}

I assume a scalaz./[NotFound[Message],Ok[Pet]] would help to handle it
for Swagger.

—
Reply to this email directly or view it on GitHub
#21 (comment).

[arouel]

Additionally we need to group the status code a bit to make something like this possible: scalaz.\/[ClientError[Message],Success[Pet]]

So we should group it as the following:

• Informational (1xx)
• Success (2xx)
• Redirection (3xx)
• Error (4xx or 5xx)
  • ClientError (4xx)
  • ServerError (5xx)

[bryce-anderson]

I believe this is closed. If not, lets make a new ticket with a summary of the problem and not reopen this thread, it seems to have strayed quite a bit from a single topic.