search

swagger-api / swagger-core

Examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API
http://swagger.io
Apache License 2.0
7.36k stars 2.17k forks source link

Update play2 module to 1.3 #307

Closed fehguy closed 10 years ago

fehguy commented 10 years ago

The play2 module is not supported with 1.3 core yet.

SimonKaluza commented 10 years ago

What official Play2 version and manually compiled swagger-core branch/tag combination can one use in the meantime to correctly build and a working java-play2 or scala-play2 sample? I've tried a variety of different combinations and though some can compile, various issues have cropped up at run-time.

phdoerfler commented 10 years ago

I'm very interested in the answer to this question, too. What's the most up-to-date combination that actually compiles?

andyoll commented 10 years ago

Check this merge request:

Steps:

fehguy commented 10 years ago

to be clear, this is not an update to swagger-core 1.3, or am I missing something?

andyoll commented 10 years ago

The reference above is about swagger-core-1.2.5 integrated with Play 2.2.0 For swagger-core-1.3 integrated with Play 2.2.0, please see my fork here:

tjslone commented 10 years ago

Thanks for the work on your fork, I have been using it and it appears to be working, except I can only get implicit parameters working, the regular parameters appear to be ignored. Have you had any trouble with these?

andyoll commented 10 years ago

Pls give me a simple example to add to test/testdata/DogController, or one of the other test controllers in there. I'll create a bunch of test cases for existing functionality tomorrow (if time allows), and then perhaps you can help me get the details right for some more test-cases that need to be implemented next. thnx.

On 25 September 2013 15:51, tjslone notifications@github.com wrote:

Thanks for the work on your fork, I have been using it and it appears to be working, except I can only get implicit parameters working, the regular parameters appear to be ignored. Have you had any trouble with these?

— Reply to this email directly or view it on GitHubhttps://github.com/wordnik/swagger-core/issues/307#issuecomment-25092425 .

tjslone commented 10 years ago

No problem - here is an example of what I was using:

tjslone commented 10 years ago

This example caused there to be no parameters returned ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// // Delete a user @ApiOperation(value = "Delete", notes = "Deletes a user", httpMethod = "DELETE") def delete( @ApiParam(name = "userId", value = "userId")@PathParam("userId") userId: String) = Action.async { implicit request => val FutureDeleteUserResult = UserModel.delete(userId) FutureDeleteUserResult.map{ case result: Boolean => { if(result) Ok("User Deleted") else BadRequest("Delete failed") } } recover { case iu: InvalidUserException => Unauthorized(iu.getMessage()) case ex: QueryErrorException => ServiceUnavailable(ex.getMessage()) case se: ServerNotAvailable => ServiceUnavailable(se.getMessage()) case _ : Exception => BadRequest("Unknown error") } } //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

tjslone commented 10 years ago

Sorry - I forgot to simplify it!! ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// // Delete a user @ApiOperation(value = "Delete", notes = "Deletes a user", httpMethod = "DELETE") def delete( @ApiParam(name = "userId", value = "userId")@PathParam("userId") userId: String) = Action.async { implicit request => Ok } //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

OliverKK commented 10 years ago

I included: "com.wordnik" %% "swagger-play2" % "1.2.5-2"

[trace] Stack trace suppressed: run last :update for the full output. [error](:update) sbt.ResolveException: unresolved dependency: com.wordnik#swagger-play2_2.10;1.2.5-2: not found [error] Total time: 6 s, completed 26.09.2013 13:50:18

It seems like this dependency con't be found.

This is my workaround to get my project compiled. "com.wordnik" %% "swagger-play2" % "1.2.5" exclude("org.scala-stm", "scala-stm_2.10.0"),

andyoll commented 10 years ago

@OliverKK

andyoll commented 10 years ago

@tjslone I have just pushed a bunch of changes to my fork (https://github.com/andyoll/swagger-core/tree/play_2.2.0-swagger_1.3) - parameter annotations are now supported, and the test coverage is increasing. I'm sure there will be some more to do, so I'd really appreciate any further feedback or failing test-cases you can give.. Stuff that I know of as work-in-progress:

OliverKK commented 10 years ago

@andyoll Thank your for the bunch of changes. Just updated today. I'm testing the 1.2.6-SNAPSHOT ("com.wordnik" %% "swagger-play2" % "1.2.6-SNAPSHOT",) in my Play2.2 / Scala project.

First thing i saw was following messages.

[error] c.w.s.c.u.TypeUtil$ - Unable to load class double [error] c.w.s.p.HelpApi - Skipping model play.api.libs.json.JsValue. Did not find any public fields or bean-properties in this model. If its a scala class its fields might not have @BeanProperty annotation added to its fields.

fehguy commented 10 years ago

@OliverKK that's not really an error, in later builds of swagger-core it is an INFO. Can you update to 1.3.1-SNAPSHOT? See here...

https://groups.google.com/forum/#!topic/swagger-swaggersocket/lN99-GetOLY

OliverKK commented 10 years ago

@fehguy @andyoll Updated right now to 1.3.1-SNAPSHOT The [error] messages turned obviously to [info] which is very good :)

Swagger returns currently: "Unable to read api 'user' from path http://localhost:9000/api-docs/api-docs/user (server returned Not Found)"

The path "...api-docs/api-docs..." seems to be wrong...

andyoll commented 10 years ago

Hi

In branch 'develop' there exist test cases showing it works nice for @ApiOperation( responseClass=

[info] + returns 'void' for 'responseClass' when not defined [info] + adds 'responseClass' when defined [info] + adds 'responseClass' correctly when defined as list

from PlayAPIReaderSpec.

The API reader only gets into action for a class or method if it is referenced in the routes file, so perhaps this is an issue? Perhaps post both routes file and controller code.

Regarding @ApiErrors - this is not supported, but there is support for: @ApiResponses -- I wonder if I was right in assuming this was the right way to do things with Swagger-core 1.3 ? I may have got this wrong..

The example play2 app may be helpful to you in demonstrating what works.

regards

Andy

On 17 October 2013 10:23, OliverKK notifications@github.com wrote:

@fehguy https://github.com/fehguy Updated right now. It seems like some annotations are not recognized anymore. @ApiErrors and @ApiOperation( responseClass=

— Reply to this email directly or view it on GitHubhttps://github.com/wordnik/swagger-core/issues/307#issuecomment-26489901 .

fehguy commented 10 years ago

Hi folks, the @ApiErrors was renamed to @ApiResponses because it's not just for documenting error states. There are some slight differences in the signature but switching between the annotations is very simple. See here:

https://github.com/wordnik/swagger-core/blob/2966229f0e9767f481aa147e2231598ae3818e80/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiError.java

https://github.com/wordnik/swagger-core/blob/2966229f0e9767f481aa147e2231598ae3818e80/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiErrors.java

and here:

https://github.com/wordnik/swagger-core/blob/master/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponses.java

https://github.com/wordnik/swagger-core/blob/master/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponse.java

OliverKK commented 10 years ago

@andyoll Thank you for the quick answer.

Following the routes and controller code:

routes

Swagger - Root Resources Listing

GET /api-docs controllers.ApiHelpController.getResources GET /api-docs/user controllers.ApiHelpController.getResource(path = "/api-docs/user")

index path

GET / controllers.Index.view

Controller: User.scala

@Path("/user") @Api(value = "/api-docs/user", description = "Manages requests for the user part of the api.") @Produces(Array("application/json")) class User @Inject() (userService: UserService) extends Controller {

@POST @Path("/user/{register}") @ApiOperation( value = "value", notes = "notes", response = classOf[Reg] ) @ApiResponses(Array( new ApiResponse(code = 110, message = "Bad JSON format."), ))

andyoll commented 10 years ago

Does your routes file define routes to the User controller? - without this the annotations are not read, cos the API is not available.

On 17 October 2013 17:28, OliverKK notifications@github.com wrote:

@andyoll https://github.com/andyoll Thank you for the quick answer.

Following the routes and controller code:

routes Swagger - Root Resources Listing

GET /api-docs controllers.ApiHelpController.getResources GET /api-docs/user controllers.ApiHelpController.getResource(path = "/api-docs/user")

index path

GET / controllers.Index.view

Controller: User.scala

@Path https://github.com/Path("/user") @Api(value = "/api-docs/user", description = "Manages requests for the user part of the api.") @Produces(Array("application/json")) class User @Inject https://github.com/Inject() (userService: UserService) extends Controller {

@POST https://github.com/POST @Path https://github.com/Path("/user/{register}") @ApiOperation( value = "value", notes = "notes", response = classOf[Reg] ) @ApiResponses(Array( new ApiResponse(code = 110, message = "Bad JSON format."), ))

— Reply to this email directly or view it on GitHubhttps://github.com/wordnik/swagger-core/issues/307#issuecomment-26524024 .

OliverKK commented 10 years ago

@andyoll Yes i define a route to my user controller.

User registration

POST /user/register @controllers.User.register()

The url's "http://localhost:9000/api-docs" and "http://localhost:9000/api-docs/user" deliver valid json.

andyoll commented 10 years ago

So I made a guess that using the @controllers syntax in order to use a class as a controller might be an issue, since I hadn't tried this. But I've added a bunch of test cases for this scenario, and they all pass so far. Next Step - I'll add a class as controller to the play2 test app, and confirm this works (or fix it if not). Hopefully I can get on to this this w/e, and let you know.

If you are in a hurry, I suggest you download the play2 test app, run it up to satisfy yourself it does what you'd expect, add a similar controller and routes to what you are playing with, and see what happens. If this doesn't work you should send me your additions to the test app that recreate this issue.

On 18 October 2013 07:42, OliverKK notifications@github.com wrote:

Yes it does:

User registration

POST /user/register @controllers.User.register()

— Reply to this email directly or view it on GitHubhttps://github.com/wordnik/swagger-core/issues/307#issuecomment-26575077 .

andyoll commented 10 years ago

@OliverKK the play2 module in branch 'develop' is 100% compatible with '@controllers syntax in order to use a class as a controller'. this pull request is full of test cases, and also an update to the scala-plauy2 sample app demonstrating this behaviour:

I suggest you get the sample app working (from this pull request branch), and then consider what you are doing differently in your app.

On 19 October 2013 10:45, Andy Olliver andy@slyfrog.com wrote:

So I made a guess that using the @controllers syntax in order to use a class as a controller might be an issue, since I hadn't tried this. But I've added a bunch of test cases for this scenario, and they all pass so far. Next Step - I'll add a class as controller to the play2 test app, and confirm this works (or fix it if not). Hopefully I can get on to this this w/e, and let you know.

If you are in a hurry, I suggest you download the play2 test app, run it up to satisfy yourself it does what you'd expect, add a similar controller and routes to what you are playing with, and see what happens. If this doesn't work you should send me your additions to the test app that recreate this issue.

On 18 October 2013 07:42, OliverKK notifications@github.com wrote:

Yes it does:

User registration

POST /user/register @controllers.User.register()

— Reply to this email directly or view it on GitHubhttps://github.com/wordnik/swagger-core/issues/307#issuecomment-26575077 .

fehguy commented 10 years ago

pushed to maven central

http://oss.sonatype.org/content/repositories/releases/com/wordnik/swagger-play2_2.10/1.3.1/

OliverKK commented 10 years ago

@fehguy @andyoll Thank you for caring about this issue and pushing to maven central. Swagger 1.3.1 works very very fine with play 2.2.

fehguy commented 10 years ago

Great @OliverKK !