Question

我们在Play 2.x之上构建了一个相对较大的REST API，并负责为我们的内部用户记录它。由于我们认为在单独的维基上维护这个很困难，我们想知道是否有任何文档生成工具用于Play？

Answer 1

Swagger提供Play 2支持：

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

Play 2本身以方便的格式为其路由器提供文档，检查当您致电时会发生什么：

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

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，或者你会得到什么东西。

仍然想知道，如果有更好的方法可以让REST-API文档无法运行......

Answer 3

我现在正在使用raml。 http://raml.org/

没有自动api doc生成。您必须手动创建和更改api文档，但这并不坏。当然，如果你改变你的api，你必须记得改变api doc;这是一个失败点。

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

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

3 个答案: