У нас есть относительно большая REST API-сборка поверх Play 2.x, и нам поручено документировать ее для наших внутренних пользователей. Поскольку мы считаем, что поддерживать это в отдельной вики очень сложно, нам интересно, есть ли какие-либо инструменты для создания документации для Play?
Swagger обеспечивает поддержку Play 2:
https://github.com/swagger-api/swagger-play
Play 2 сам обеспечивает документацию для своего маршрутизатора в удобном формате, проверка того, что происходит, когда вы вызываете:
Play.current.routes.foreach(r => println(r.documentation))
Я думаю, в 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 из игры...
Теперь я использую raml. http://raml.org/
Нет автоматического генерации api doc. Вы должны создать и изменить api docs вручную, но это совсем не плохо. Конечно, если вы измените свой api, вы должны помнить об изменении api doc; Это точка отказа.
Но хорошо это: вы не загрязняете свой код комментариями и комментариями api doc. Это самый важный момент для меня. "Язык api doc" очень прост в освоении/использовании.