Automatic body parameters

[lynx44]

I'm fairly sure this isn't supported since it doesn't seem to happen automatically and I didn't see anything in the code that would handle it, but before working on a pull request I wanted to confirm that play-swagger should not automatically generate documentation for body parameters.

For example:

def test = Action(parse.json[TestResource]) { implicit request => Ok }

with no extra documentation in the routes file:

POST /test controllers.ApplicationController.test

Does not generate the body parameter automatically:

"/test":{"post":{"tags":["routes"],"parameters":[{"name":"body","schema":{"$ref":"#/definitions/org.example.project.TestResource"},"in":"body"}],"consumes":["application/json"]}}

I feel like that would be possible to do automatically with reflection - would that fit the vision of the project?

It'd also be nice if we could do this with return parameters, although i'm not sure how feasible that would be at runtime.

[kailuowang]

That's an interesting idea. It would be cool to have such a feature. There are a couple of things that we have to keep in mind,

1. Adding reflection on the action method will increase the coupling between play controller implementation and play-swagger. Right now we have reflection but only on simple domain case classes.
2. we are considering moving towards compilation time schema generation, see https://github.com/iheartradio/play-swagger/pull/85

I am really curious to see if you can get it working, we probably just need to make sure the logic is modularized properly.

[lynx44]

I ended up creating this as a plugin. I had to make some changes to the SwaggerSpecGenerator to create some extension points. It may need some cleanup, but I can create a pull request if it looks reasonable.

I also created a new play library to create more strongly typed actions called play-stringent, which makes this possible. I use reflection to read the method signature, which reveals which response codes are being returned.

The plugin library is called play-swagger-reflect. I've published a snapshot to sonatype, and there's documentation on the page. All you really need to know is in the README in that repository.

It'd be great to get some feedback if you have time to check it out. Obviously it's incomplete, but I think it's in a usable state.

[Javakky-pxv]

@lynx44 I may no longer be used, but I would like to use this feature when renewing it as Ver 2.0.0 ! It may be a while before that happens, but I would like to use it while complying with the license 🙇

[lynx44]

Sure, feel free to use anything you'd like. If you need me to update/change any licenses, I'm happy to do so. I haven't used play or scala in quite a few years.