Adding Swagger documentation to the Scala project with Play Framework

[Vlad]

Hello. I'm developing a project on Scala using Play Framework 2.x and I'd like to cover its API with Swagger documentation. I've used this guide to do it, but as it turns it it uses the old version of Swagger, not 2.0. Could anyone provide any tips and hints as to how to create a documentation for my project using Swagger 2.0 specification? As I understand it, I should manually write the documentation in JSON or YAML and then configure my Play routes so that the route to the documentation will return the YAML written by me, which will be then displayed by the Swagger UI. 

I've also found Scala plugin but unfortunately I wasn't able to sort out how to make it work with my project, albeit I've successfully installed it.

[Kjetil Matheussen]

Hi, here's another alternative: https://github.com/sun-opsys/api-doc

It supports swagger 2.0 with either Play 2.3 or Play 2.4.

On Wed, Jul 29, 2015 at 1:45 PM, Vlad <guze...@gmail.com> wrote:

Hello. I'm developing a project on Scala using Play Framework 2.x and I'd like to cover its API with Swagger documentation. I've used this guide to do it, but as it turns it it uses the old version of Swagger, not 2.0. Could anyone provide any tips and hints as to how to create a documentation for my project using Swagger 2.0 specification? As I understand it, I should manually write the documentation in JSON or YAML and then configure my Play routes so that the route to the documentation will return the YAML written by me, which will be then displayed by the Swagger UI. 

I've also found Scala plugin but unfortunately I wasn't able to sort out how to make it work with my project, albeit I've successfully installed it.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Vlad]

Thank you! It looks quite promising, I'm gonna look at it a bit later.

[Vlad]

Hi. I've looked up the alternative you've suggested and got a little confused. Have I understood it right that I have to manually copy the code from the GitHub project to mine in order to make the documentation work? There is no way I can take the GitHub project and extend it because my project is already quite big and complicated.

[Kjetil Matheussen]

Sorry about that. Haven't gotten around to publish it anywhere. (Need to find a new name too for that, suggestions are welcomed!)

However, you can write "publishLocal" in sbt, and then copy the produced jar file into your "lib" directory. (haven't tried, but should work)

Or, like we do, have it as a git subproject by importing it as a git subtree. (git submodule would also be an option)

[Vlad]

I've tried to do some stuff with it but unfortunately I wasn't able to make it work. So, I guess I'll stick to writing documentation manually for now.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Kjetil Matheussen]

Sorry to hear that. But for the record, the code is thoroughly tested, and we've used it for over a year in our project.

There are also at least one other company that's using it  (they've been submitting pull requests).

Doesn't the example project work?

("activator run", and then go to http://localhost:9000/swagger-ui/dist/index.html?url=http://localhost:9000/api/v1/api-docs)

It would also be interesting to know what happened, for instance so that we could show better error messages.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Vlad]

The example works and it's very nice. I was just unable to connect your project to my project as a dependency. What I've done: 

I've published your project using sbt 'publishLocal'. Then I've added your project as a dependency to my build.sbt and refreshed the project (I'm using Intellij IDEA if that matters). After I've done it, IDEA seemed to resolve all dependencies and I still wasn't able to use the annotations as you've done in your project. 

On Saturday, 1 August 2015 13:41:35 UTC+3, Kjetil Matheussen wrote:

Sorry to hear that. But for the record, the code is thoroughly tested, and we've used it for over a year in our project.

There are also at least one other company that's using it  (they've been submitting pull requests).

Doesn't the example project work?

("activator run", and then go to http://localhost:9000/swagger-ui/dist/index.html?url=http://localhost:9000/api/v1/api-docs)

It would also be interesting to know what happened, for instance so that we could show better error messages.

On Sat, Aug 1, 2015 at 12:29 PM, Vlad <guze...@gmail.com> wrote:

I've tried to do some stuff with it but unfortunately I wasn't able to make it work. So, I guess I'll stick to writing documentation manually for now.

On Friday, 31 July 2015 09:21:07 UTC+3, Kjetil Matheussen wrote:

Sorry about that. Haven't gotten around to publish it anywhere. (Need to find a new name too for that, suggestions are welcomed!)

However, you can write "publishLocal" in sbt, and then copy the produced jar file into your "lib" directory. (haven't tried, but should work)

Or, like we do, have it as a git subproject by importing it as a git subtree. (git submodule would also be an option)

On Thu, Jul 30, 2015 at 7:27 PM, Vlad <guze...@gmail.com> wrote:

Hi. I've looked up the alternative you've suggested and got a little confused. Have I understood it right that I have to manually copy the code from the GitHub project to mine in order to make the documentation work? There is no way I can take the GitHub project and extend it because my project is already quite big and complicated.

On Wednesday, 29 July 2015 15:10:10 UTC+3, Kjetil Matheussen wrote:

Hi, here's another alternative: https://github.com/sun-opsys/api-doc

It supports swagger 2.0 with either Play 2.3 or Play 2.4.

On Wed, Jul 29, 2015 at 1:45 PM, Vlad <guze...@gmail.com> wrote:

Hello. I'm developing a project on Scala using Play Framework 2.x and I'd like to cover its API with Swagger documentation. I've used this guide to do it, but as it turns it it uses the old version of Swagger, not 2.0. Could anyone provide any tips and hints as to how to create a documentation for my project using Swagger 2.0 specification? As I understand it, I should manually write the documentation in JSON or YAML and then configure my Play routes so that the route to the documentation will return the YAML written by me, which will be then displayed by the Swagger UI. 

I've also found Scala plugin but unfortunately I wasn't able to sort out how to make it work with my project, albeit I've successfully installed it.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Kjetil Matheussen]

Tried it, and you are right, publish didn't work quite right. It doesn't include all necessary files.

I've fixed this now and added a quick and dirty recipe on how to include it in other projects.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.