This bundle could support Swagger-compliant JSON. This would have several benefits:
In order to do this, we need to be able to also document input/output models for api methods. The bundle already supports documenting input models via the formType property, and there is a proposal to allow documenting return types in #47.
If these issues are taken care of, supporting Swagger JSON could be done by implementing a new SwaggerFormatter, and adding a new controller action in ApiDocController, which would return the necessary resources.json spec.
For interested parties, started a conversation about this on the Swagger google group here: https://groups.google.com/forum/#!topic/swagger-swaggersocket/3Ku5SgKg9kw
Is there anyone who happens to be in active effort to implement this feature?
I would love to see this happen and I'm willing to contribute if there is an active effort. If there is none, I would like to know too so that I could go ahead and start one.
@bezhermoso I was never able to get the time back to continue my efforts... I can describe where I left off, but it has been a while, and I'm not sure what all has changed since I last worked on it.
I think the open issues mostly cover it, but the biggest thing that needed to happen was that Parsers need to return consistent values for dataType. If they did that, you should be able to write a formatter that converts the input/return structures into JSON Schema, which is used by Swagger.
One other thing probably needs to happen too, though, and I'm not sure if there's an issue open or not. It's relatively common to return things like this from an API controller:
return ['user' => $user]
Right now, there isn't an easy way to reconcile that with the @ApiDoc return property. You could maybe build a wrapping return class and use that in the ApiDoc annotation, but that's insanely tedious. It would be nice to be able to just declare that the returned value is under another top-level property.
@evillemez Please see #410 As you have worked on this at some extent in the past, can you give feedback?
I created a PR on providing a uniform way of specifying data types: #413
Development of a formatter that produces Swagger-compliant JSON will follow if this does get merged in. (crossfingers)
Update: I created another PR which when accepted would move us closer to this goal.
Thanks @bezhermoso - Finally this can get closed when #418 makes it in!
@evillemez You're welcome! My fingers are crossed -- I hope it will get through. :)
... aaaand close. Congrats @bezhermoso