Narzędzia do tworzenia dokumentacji dla API RPC

Question

Istnieje wiele dobrych narzędzi do kodowania kodu źródłowego i dokumentacji API (Doxygen, Headerdoc, Sphinx, aby wymienić tylko kilka). Jednak żadna z nich nie wydaje się szczególnie dobra przy tworzeniu dokumentacji dla interfejsów API, które są dostarczane za pośrednictwem interfejsu RPC (jeśli masz zalecenia dotyczące syntezy dokumentacji API RPC z tymi narzędziami, wszelkimi sposobami sugeruj to).

jestem specjalnie zainteresowany narzędzi dokumentacji, które mają co najmniej pewne wsparcie dla JSON i AMQP, ale pytanie byłoby również stać na takie rzeczy jak Protobuf, Thrift i XML-RPC i wszelkie sugestie narzędzie, które współpracują z tych technologii będzie na przynajmniej daj mi miejsce do rozpoczęcia.

Szczerze mówiąc, muszę jeszcze zobaczyć dokumentację jakościową dla dowolnego interfejsu RPC (produkowanego ręcznie lub za pomocą narzędzia), i mam nadzieję, że to dlatego, że programiści są leniwi, a nie dlatego, że narzędzia nie istnieją.

Answer 1

Spójrz na Swagger (http://swagger.wordnik.com) - to jest to, czego używamy dla wszystkich naszych apis w 3scale (http://www.3scale.net). Zasadniczo zajmie to specyfikację JSON i zrobi różne rzeczy, w tym tworzenie interaktywnych dokumentów API dla ciebie. Dokumenty w stylu RPC powinny być w porządku (zmieniliśmy je, aby pobrać/odebrać XML). Istnieją również narzędzia do generowania specyfikacji z kodu dla różnych języków.

Wreszcie istnieje proste narzędzie do wyciągania kodu, które może utworzyć JSON: https://github.com/solso/source2swagger. Wszystko to jest mniej sformalizowane niż Doxygen itp., Ale może być przydatne do wyewidencjonowania.