Có bất kỳ plugin nào để tạo tài liệu API cho Play 2.x không?

Question

Chúng tôi có một API REST tương đối lớn trên đầu trang Play 2.x và được giao nhiệm vụ ghi lại tài liệu cho người dùng nội bộ của chúng tôi. Vì chúng tôi tin rằng việc duy trì điều này trên một wiki riêng biệt là rất khó khăn, chúng tôi đang tự hỏi liệu có bất kỳ công cụ tạo tài liệu nào ở đó cho Play không?

Answer 1

Swagger cung cấp Chơi 2 hỗ trợ:

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

Chơi 2 tự cung cấp tài liệu hướng dẫn để định tuyến của nó trong một định dạng thuận tiện, kiểm tra những gì sẽ xảy ra khi bạn gọi:

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

Answer 2

tôi đoán, trong Chơi 2.4, bạn sẽ tiêm bộ định tuyến:

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

Nhưng, đây không thực sự là một tài liệu API tốt. Bạn không nhận được, những thứ bạn phải POST, hoặc những thứ bạn sẽ GET.

Vẫn tự hỏi, nếu có cách nào tốt hơn để có tài liệu REST-API không hoạt động ...

Answer 3

Tôi hiện đang sử dụng raml. http://raml.org/

Không có tự động tạo tài liệu api. Bạn phải tạo và thay đổi tài liệu api theo cách thủ công, nhưng điều này không hề tệ chút nào. Chắc chắn, nếu bạn thay đổi api của bạn, bạn phải nhớ thay đổi tài liệu api; Đó là một điểm thất bại.

Nhưng điều này là: Bạn không gây ô nhiễm mã của bạn bằng chú thích và nhận xét về tài liệu api. Đó là điểm quan trọng nhất đối với tôi. "Ngôn ngữ api doc" thực sự dễ học/sử dụng.