descriptive-play-swagger now supports Play framework 2.7
descriptive-play-swagger is a fork of play-swagger. A SBT plugin that allows you to write comments on play framework routes file, together with the scaladoc to generate the full swagger documentation.
Play-swagger rocks, a SBT plugin is probably the best way to generate documentation. Unlike other solution on the market, which normally require you to use annotation on your source files. Soon enough your import section will be polluted by import i.have.no.idea.what.these.are dependencies. Imagine all the efforts when the plugin changes the package name. Oh my…
Play-swagger takes a different route. No more imports, just comments. You write comments on the play framework routes file and play-swagger will use reflection to generate all the swagger document for you.
It gets the job done, and gets it done very nicely. With only one exception: You can not have description on the API parameters or model fields. This is inevitable, reflection works on generated bytecodes, not the source files. This is why I forked this project and started adding my solution.
descriptive-play-swagger actually consists of two parts:
- An extension of play-swagger that accepts one additional parameter used to supply the descriptions.
- The doc-extract SBT plugin to extract scaladoc into a text file.
Installation
The installation is straight forward, things are just happening under the hood.
#plugins.sbt
addSbtPlugin("com.sohoffice" %% "sbt-descriptive-play-swagger" % "0.7.5")#build.sbt
resolvers += Resolver.bintrayIvyRepo("sohoffice", "sbt-plugins")
lazy val root = (project in file("."))
.enablePlugins(PlayScala, SwaggerPlugin)
Demo
The below is a very simple demonstration of how things work. Note the descriptions were generated beside model parameters, which is quite blanky using play-swagger alone. Check it out in github.
Conclusion
The project is still very young, with very little usage, if any. As a result I don’t maintain any kind of backward compatibility. It will only support the current play framework version used in my project, at this moment, version 2.7. But I still hope you will enjoy it.
Other swagger articles
Did you learn something new? If so please:
↓ clap 👏 button below️ so more people can see this.
