有没有用于生成Play 2.x API文档的插件？

Question

我们有一个基于Play 2.x构建的相对较大的REST API，并被要求为我们内部用户编写文档。由于我们认为在单独的wiki上维护这个文档非常困难，因此我们想知道是否有任何Play文档生成工具可用？

- Mad Dog

Answer 1

Swagger提供了Play 2的支持：

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

Play 2本身以方便的格式为其路由器提供文档，当您调用以下内容时，请检查发生了什么：

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

- James Roper

Answer 2

我猜，在Play 2.4中，你需要注入路由器:

  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))
    }
  }

但是，这并不是一份好的API文档。你无法获得需要POST的内容或者将会GET到什么内容。

我仍然在思考，是否有更好的方法来获取Play框架的REST API文档...

- gun

Answer 3

我现在正在使用raml。 http://raml.org/ 没有自动的api文档生成。您必须手动创建和更改api文档，但这并不坏。 当然，如果您更改了api，则必须记住同时更改api文档；这是一个失败的点。

但好处是：您不会用注释和api文档注释来污染您的代码。对我来说，这是最重要的一点。 “api文档语言”真的很容易学习/使用。

- gun