Các công cụ tài liệu cho các API RPC

Question

Có nhiều công cụ tốt cho tài liệu API và mã nguồn (Doxygen, Headerdoc, Sphinx, để đặt tên nhưng một vài). Tuy nhiên, không ai trong số họ xuất hiện đặc biệt giỏi trong việc tạo tài liệu cho các API được cung cấp qua giao diện RPC (nếu bạn có các khuyến nghị về cách tổng hợp tài liệu API RPC với các công cụ này, bằng mọi cách gợi ý nó).

Tôi đặc biệt quan tâm đến công cụ tài liệu đó có ít nhất một số hỗ trợ cho JSON và AMQP, nhưng câu hỏi cũng sẽ đại diện cho những thứ như Protobuf, Thrift, và XML-RPC và bất cứ đề nghị công cụ làm việc với những công nghệ sẽ ở ít nhất là cho tôi một nơi để bắt đầu.

Tôi thực sự chưa thấy tài liệu chất lượng cho bất kỳ giao diện RPC nào (hoặc được sản xuất bằng tay hoặc bằng công cụ), và tôi chỉ hy vọng đó là vì các nhà phát triển lười biếng chứ không phải vì các công cụ không tồn tại.

Answer 1

Hãy xem xét Swagger (http://swagger.wordnik.com) - đây là những gì chúng tôi sử dụng cho tất cả các apis của chúng tôi tại 3scale (http://www.3scale.net). Về cơ bản, nó sẽ lấy thông số JSON và thực hiện nhiều việc khác nhau bao gồm tạo tài liệu API tương tác cho bạn. Tài liệu phong cách RPC nên được sử dụng tốt (chúng tôi đã sửa đổi nó để lấy/nhận XML). Ngoài ra còn có các công cụ để tạo ra các thông số kỹ thuật từ mã cho các ngôn ngữ khác nhau.

Cuối cùng, có một công cụ trích xuất mã đơn giản có thể tạo JSON: https://github.com/solso/source2swagger. Tất cả điều này là ít chính thức hóa hơn Doxygen vv nhưng có thể hữu ích để kiểm tra.