Are there any plugins for generating API documentation for Play 2.x?

Question

We have a relatively large REST API build on top of Play 2.x and are tasked with documenting it for our internal users. Since it is our belief that maintaining this on a separate wiki is very difficult, we are wondering if there are any documentation generating tools out there for Play?

Answer 1

Swagger provides Play 2 support:

https://github.com/swagger-api/swagger-play

Play 2 itself provides documentation to its router in a convenient format, checkout what happens when you call:

Play.current.routes.foreach(r => println(r.documentation))

Answer 2

I guess, in Play 2.4, you would inject the router:

  class Health @Inject() (router: Router) extends Controller {
    def doc = Action { implicit request =>
      val myroutes = router.documentation.map {
        x => Json.obj("http_method" -> x._1, "path" -> x._2, "scala" -> x._3)
      }
      Ok(Json.obj("k" -> myroutes))
    }
  }

But, this is not really a good API documentation. You don't get, what stuff you have to POST, or what stuff you will GET.

Still wondering, if there ist a better way to get a REST-API documentation out of play...

Answer 3

I am using raml now. http://raml.org/

There is no automatic api doc generation. You have to create and change the api docs manually, but this is not bad at all. Sure, if you change your api, you have to remember to change the api doc as well; That is a point of failure.

But the good this are: You don't pollute your code with annotations and api doc comments. Thats the most important point for me. The "api doc language" is really easy to learn/use.