Инструменты документации для API RPC

Существует множество хороших инструментов для исходного кода и документации API (Doxygen, Headerdoc, Sphinx, чтобы назвать лишь несколько). Тем не менее, ни одна из них не особенно хороша при подготовке документации для API-интерфейсов, предоставляемых через интерфейс RPC (если у вас есть рекомендации по синтезу документации RPC API с помощью этих инструментов, непременно укажите ее).

Меня особенно интересуют инструменты документации, которые, по крайней мере, поддерживают JSON и AMQP, но вопрос будет также стоять за такие вещи, как Protobuf, Thrift, а XML-RPC и любые предложения по инструментам, которые работают с этими технологиями, по крайней мере дают мне место для начала.

Я, честно говоря, еще не видел качественную документацию для любого интерфейса RPC (созданного вручную или с помощью инструмента), и я просто надеюсь, что разработчики ленивы, а не потому, что инструменты не существуют.

Ответы

Ответ 1

Взгляните на Swagger (http://swagger.wordnik.com) - это то, что мы используем для всего нашего apis в 3scale (http://www.3scale.net). В основном это будет спецификация JSON и делать различные вещи, включая создание интерактивных документов API для вас. Документы стиля RPC должны быть точными (мы внесли поправки, чтобы принять/получить XML). Существуют также инструменты для генерации спецификаций из кода для разных языков.

Наконец, есть простой инструмент для выделения кода, который может создать JSON: https://github.com/solso/source2swagger. Все это менее формализовано, чем Doxygen и т.д., Но может быть полезно проверить.