Esistono plug-in per generare documentazione API per Play 2.x?

Question

Abbiamo una build di API REST relativamente grande in cima a Play 2.x e abbiamo il compito di documentarla per i nostri utenti interni. Dal momento che è nostra convinzione che mantenere questo in un wiki separato sia molto difficile, ci chiediamo se ci sono strumenti di generazione di documentazione là fuori per Play?

Answer 1

Swagger fornisce Play 2 supporto:

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

Play 2 si fornisce la documentazione al suo router in un comodo formato, cassa che cosa succede quando si chiama:

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

Answer 2

Credo che, in Gioca 2.4, dovresti iniettare il 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)) 
    } 
    } 

Tuttavia, questa non è una buona documentazione API. Non ottieni, quali cose hai per POST, o quali cose otterrai.

Ancora chiedendo, se ci ist un modo migliore per ottenere una documentazione REST API fuori gioco ...

Answer 3

sto usando Raml ora. http://raml.org/

Non esiste una generazione automatica di documenti API. Devi creare e modificare manualmente i documenti API, ma non è affatto male. Certo, se cambi la tua API, devi ricordarti di cambiare anche il documento api; Questo è un punto di fallimento.

Ma il bello è questo: non si inquina il codice con annotazioni e commenti api doc. Questo è il punto più importante per me. Il "linguaggio api doc" è davvero facile da imparare/usare.