Czy są jakieś wtyczki do generowania dokumentacji interfejsu API dla Play 2.x?

Question

Mamy stosunkowo duży interfejs REST API zbudowany na Play 2.x i ma za zadanie udokumentowanie go dla naszych wewnętrznych użytkowników. Ponieważ wierzymy, że utrzymywanie tego na osobnej wiki jest bardzo trudne, zastanawiamy się, czy istnieją jakieś narzędzia generujące dokumentację dla Play?

Answer 1

Swagger zapewnia grać 2 Wsparcie:

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

Odtwórz 2 Sam dostarcza dokumentację do swojego routera w wygodnym formacie, kasa, co się dzieje, kiedy zadzwonić:

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

Answer 2

Chyba w W wersji 2.4 wstrzykniesz 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)) 
    } 
    } 

Ale to nie jest dobra dokumentacja API. Nie dostaniesz, jakie rzeczy masz na POST lub jakie rzeczy będziesz miał.

Wciąż zastanawiasz się, jeśli nie ist lepszy sposób, aby uzyskać dokumentację REST API z gry ...

Answer 3

Używam Raml teraz. http://raml.org/

Nie ma automatycznego generowania dokumentów api. Musisz ręcznie tworzyć i zmieniać dokumenty API, ale to wcale nie jest złe. Oczywiście, jeśli zmienisz swoje API, musisz pamiętać, aby zmienić także dokumentację api; To jest punkt awarii.

Ale to jest dobre: ​​nie zanieczyszczasz swojego kodu adnotacjami i komentarzami api-doc. To jest dla mnie najważniejsze. "Język api doc" jest naprawdę łatwy do nauczenia/użycia.