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

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

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

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

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

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

  • Укажите формат/структуру URL/URI
  • Форматы и методы запроса/ответа (GET/POST/etc, XML/JSON/etc)
  • Классифицировать конечные точки/вызовы 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/

Ответы

Ответ 1

SWAGGER, вероятно, стоит того, чтобы вам было нужно. Я использую его для документирования точек входа REST, представленных java-приложением с использованием Джерси, но похоже, что вы можете использовать его и на других языках.

Ответ 2

Одна из причин, по которой такой инструмент не существует, заключается в том, что документация RESTful API не должна включать любой из этих элементов:

  • Укажите формат/структуру URL/URI
  • Форматы и методы запроса/ответа (GET/POST/etc, XML/JSON/etc)
  • Классифицировать конечные точки/вызовы API (например, группировать несколько вызовов под аутентификацией)

Документация RESTful API связана с документированием используемых типов носителей и их связанной семантикой приложений. Вы должны искать что-то, что больше похоже на this.

Приведенными примерами являются API-интерфейсы RPC, основанные на HTTP, поэтому они требуют такой документации о конечных точках. Они RESTful только по названию. Теперь, почему люди не создают инструменты для автоматического документирования API-интерфейсов RPC на основе HTTP, я не могу вам сказать. Может быть, это потому, что люди, которые пишут эти API, настолько заняты, что им не хватает времени на разработку инструментов для документации!

Ответ 3

После долгих исследований я обнаружил, что это не инструмент, который делает именно то, что я хочу. Там есть ряд инструментов, которые являются очень важным шагом в правильном направлении, но часто зависят от языка и не создают справочную документацию API HTTP/RPC, а скорее справочную документацию по Code/Library/API.

В результате я планирую создать инструмент, который мне нужен /envision с нуля. Если/когда мне нужно что-то показать, я обновлю свой ответ.

Ответ 4

Вы должны взглянуть на приложение Swagger, как уже упоминалось @zim2001. Он имеет компонент Swagger-ui, который представляет собой простое приложение html и javascript, которое считывает данные json, записанные в бэкэнд-приложении. Существуют адаптеры для количества языков, включая php и java.

Если вы используете инфраструктуру Symfony2 для PHP, вот готовый к использованию пакет для автоматической генерации сервисной документации RESTful:

Одной из вещей, которые мне не нравятся в таких генераторах, является отсутствие переводов, поэтому, если вы хотите предоставить документацию по вашему API, представленную через службы RESTful на многих языках, вы не можете.