finch
finch copied to clipboard
finagle
Swagger documentation auto-generation support
Swagger is a RESTful API Documentation Specification, most popular one for the moment: https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md It is like WSDL and WADL but a lot less horrible to work with. It comes with swagger-ui which is pure HTML+JS app to interactively explore a Swagger-enabled REST API. It can be easily integrated into your website and serve as a documentation for developers. Sample: http://petstore.swagger.wordnik.com/
A Swagger doc can be written manually but it's better to have it auto-generated. We're all for self-documenting API's, don't we? Please, consider to add support for it in finch.
At least, I beg to let the routing be programmatically inspectable so support for it can be implemented by a 3d party. It is what is missing in Spray.io and seems like the issue can never be addressed in a sane way because of the way it's routing is implemented: https://groups.google.com/forum/#!searchin/spray-user/swagger/spray-user/P_6kNIfT7FQ/YNLq0AZmwx8J
Thanks @migesok!
The sample looks great! I will think about implementing Swagger support in the next milestone,
My gut reaction is that this isn't possible without a lot of work. The representation of routes is very much a final encoding, preserving no where near the richness of data required. We would neeed some initial encoding that we compiled to, or a set of conbinators like those used in web-routes-boomerang (on hackage).
It's a very worth goal. I might have a crack at throwing together a design on the weekend.
I've been thinking about this one for awhile and fiddling with some code. You're right, its a lot of work. My impressions so far:
- From what I've seen the swagger api is kinda unwieldy and we cannot cleanly support anywhere near all its features without changing routing significantly (I mean something that's way beyond an intermediate encoding. the api would need to include descriptions and other meta data).
- I think its a niche enough that we should consider not supporting it in this library and instead having an user supported library outside of this repository.
- As to actually implementing it, the answer I've arrived at so far is macros (at least for maintaining the same API or making routing inspectable).
Macros would let us have a construct similar to Endpoint except it would also generate the swagger endpoint to return json, filled out swagger template, or whatever. It would also allow us to avoid an intermediate encoding.
I'd agree that it could be slapped into a jar outside the finch project.
When I said initial I meant in the category theoretic sense, so yes to the points about meta-data etc. I would imagine a set of combinators that generated some kind of AST that could be transformed down into the route value after the swagger yaml had been gen'd out of it. Definitely sounds like a macro would work.
I personally am not a huge fan of swagger, but people seem to like it :)
Ah, now I understand. That sounds like a solid approach. I'm interested to see what you come up with.
I'm also interested in swagger support here.
I haven't looked at the implementation to consider how much work it is. I've used swagger with Scalatra in the past and found it to be pretty straightforward.
Example:
val getFlowers =
(apiOperation[List[Flower]]("getFlowers")
summary "Show all flowers"
notes "Shows all the flowers in the flower shop. You can search it too."
parameter queryParam[Option[String]]("name").description("A name to search for"))
get("/", operation(getFlowers)) {
params.get("name") match {
case Some(name) => FlowerData.all filter (_.name.toLowerCase contains name.toLowerCase)
case None => FlowerData.all
}
}
Something really awesome happening right now in the Swagger project (https://github.com/swagger-api/swagger-codegen/issues/3132).
Something amazing happened! https://twitter.com/wing328/status/825564638393704448
It's now possible to generate Finch server stubs out of Swagger API definitions. Amazing work by @jimschubert and @wing328!
Does this mean that the work of going from Finch -> Swagger-doc is abandoned? While the swagger->finch path is interesting, I think it's a completely separate problem from keeping documentation up-to-date as a REST API evolves.
@aroberts, I don't think it this has been abandoned (not sure it ever made it passed the idea phase). I've been thinking about it a lot recently because we started using a tool like Swagger at work. Its not an easy problem and Finch isn't quite setup to support it yet. I'm probably going to try to tackle some of the Endpoint metadata stuff this weekend, which would put us in a better place.
As a side note, Fintrospect went in a different direction than Scalatra for implementing this, and I think its probably worth drawing inspiration from.
Honestly, I think a design first approach is more useful than just having documentation generated from the code. Therefore, I'm a whole lot more interested in generating code from swagger docs than the other way around.
@spockz how would you handle regeneration when your definitions change?
aside @rpless I'm realizing that my documentation case isn't as straightforward as I thought, as there's unavoidable manual curation and parameters I don't want exposed in the docs. Really, I think my ideal solution is something like compile-time checking that the documentation isn't lying - finch payloads matching swagger definitions, no documented parameters that don't exist, etc. It's clear to me that this is a much more challenging problem to solve statically, but having the meta in place would at least be a starting place for me to approach a solution.
@aroberts. In Jersey only the interfaces are generated. Similarly we can, preferably at runtime, generate the traits containing the Finch endpoint definitions. That way we don't need to check anything, we know.
Is this a dead ticket, What was the result? Also Is the finch generator reliable ?
