Каков наилучший инструмент для документирования / создания справочника для RESTful / HTTP RPC API? [закрыто]

Закрыт. Этот вопрос не по теме . В настоящее время он не принимает ответы.

Хотите улучшить этот вопрос? Обновите вопрос , чтобы он был по теме для Stack Overflow.

Закрыт 5 лет назад .

Многие вопросы были опубликованы и даны ответы об API на основе REST / HTTP и т. Д., Но ни один, похоже, не содержит подробной информации по следующему вопросу:

Какие инструменты доступны / используются для документирования HTTP-RPC API? Какие инструменты лучше всего?

Аналогичный вопрос (для ASP.NET) от января 2009 года можно найти здесь , но без ответов.

Я разрабатываю несколько API как для профессиональных, так и для личных проектов (.NET MVC / OpenRasta, PHP, Coldfusion и т. д.), и я не нашел ничего, что помогло бы задокументировать эти API. Я не ищу автогенерацию на основе парсинга / очистки кода или чего-то подобного. Как вы, наверное, уже знаете, API на основе RESTful / HTTP должен быть независимым от клиента и платформы; поэтому я ожидаю, что любой инструмент документации будет таким же.

Возможности, которые может иметь достойный инструмент:

Указание формата / структуры URL-адресов / URI
Форматы и методы запросов / ответов (GET / POST / и т. Д., XML / JSON и т. Д.)
Категоризация конечных точек / API Вызовы (например, группировка нескольких вызовов при аутентификации)
Автоматическое создание статических справочных файлов / документации, как в примерах ниже
Включите примеры, контрольные примеры и т. Д.

Вот несколько примеров того, что я считаю достойной документацией по API / ссылки выглядят так:

http://dev.twitter.com/doc/post/statuses/destroy/:id

http://www.salesforce.com/us/developer/docs/ api_rest / index.htm

http://www.flickr.com/services/api/