Lack of example field in Swagger Propertys?

[changlinli]

Rho's Swagger Property doesn't have an example field whereas the Property interface in the swagger-models does have a getExample and setExample. I think this shows up for example in how Swagger-UI is able to construct an example for a piece of JSON by concatenating together the examples for each of its constituent parts.

Is there any reason that was omitted? If not is adding it any more complicated than this commit?

Rho and Swagger noob here so trying to make sure I'm not overlooking something.

[bryce-anderson]

No particular reason it was omitted. Your commit adds support in the swagger representation, but to be useful it would also need to be settable in the route construction API. If this is a feature you're interested in working on, I'm certainly not opposed to another great PR or two. 😄

[changlinli]

Hmmm... I'd love to take a whack at it, but I'm probably going to need some guidance from you or other more experienced Rho people about the best way to integrate this into the existing Rho code. From what I understand of the route construction API and Swagger (which again is very little), it seems like this isn't something that would be directly addressed in the route construction, but rather is something that needs to happen at the model level, i.e. with some sort of custom SwaggerFormats that then gets passed in at route construction.

On the upside I think #183 lays some of the foundation for this, but it doesn't seem quite enough. It seems like to do this well, you'd want some nice way of constructing and composing custom SwaggerFormats for each of your custom types (potentially beyond the low-level-ish withFieldSerializers and the like) and along the way would construct custom example fields (potentially customizing other fields as well). A strawman for that might be something like the typeclass approach that shows up in serialization libraries all over the place (since really we're just serializing to a Swagger model).

I'm also wary of hitching this on such an ambitious change when I both don't understand the Rho codebase (or even its public API) all that well and when I suspect you might be able to get examples working without needing to embark on a long journey with a high risk of noncompletion...

Thoughts? Go for a general approach or is there some sort of specific thing I could do here that would could get this done quite simply? Or maybe the general approach is already there and I could just piggy-back off that (or maybe the general approach isn't even that difficult to begin with)?

[changlinli]

Oh never mind, I missed the fact that we want this at the type level, not the value level. In which case it might already be enough to just expose SwaggerFormats to allow users to add examples. I was hoping to have use an implicit SwaggerFormats of an intermediate type A used in the construction of another type B to allow for an automatic modification of type B, but that looks increasingly like it's going to need Shapeless, which might be okay considering that you already have it as a dependency. But that might be a bridge too far in terms of arcane implicit magic...

[bryce-anderson]

It would definitely be a challenge, but if you want, a first step would be to surface the swagger Java API in our own. Worst case: it goes unused.

[changlinli]

Did you mean surfacing it in some other way than just in Property? Because I think you can already get at the example by writing out a SwaggerFormats manually.