swagger-api / swagger-play

Apache License 2.0
330 stars 181 forks source link

Inaccurate docs (JAX refs) #84

Closed slouc closed 8 years ago

slouc commented 8 years ago

I think there are some leftover JAX references, for example line

@ApiParam(value = "ID of the pet to fetch") @PathParam("id") id: String) = Action {

which uses PathParam annotation. I discovered that PathParam is a JAX-RS annotation and therefore tried to make things work with ApiImplicitParam, but without luck. I ended up using a completely different library and it works well. So just a word of feedback - update your docs. They should be as accurate and as simple as possible, without user having to navigate all the way here in order to find out that the reason why PathParam is not available for import is because it's a JAX-RS thing.

Perhaps I am missing something, but in any case make sure to be more precise in the docs, otherwise you frustrate users who c/p your snippet hoping things will work out-of-the-box, only to discover that PathParam is nowhere to be found for import.

fehguy commented 8 years ago

Fixed in https://github.com/swagger-api/swagger-play/commit/7ba5fc873a94819b28478a189c699556a6bf71d4