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

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

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

Аналогичный вопрос (специфический для 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/


api rest documentation-generation
person Colin    schedule 06.06.2011    source источник
comment
lunatech-labs.com/open-source/jax-doclets выглядит многообещающе, но я не использовал его сам. Кроме того, он специфичен для Java, хотя, возможно, лежащие в его основе идеи будут перенесены на другие языки...   -  person MatrixFrog    schedule 06.06.2011
comment
Было бы здорово, если бы я использовал Java: P Однако это определенно было бы полезно для будущих проектов Java, так что спасибо за ссылку!   -  person Colin    schedule 06.06.2011
comment
Я создал простой шаблон для документации RESTful API: github.com/berb/rest-doc-template Возможно, это будет полезно и вам. Если нет, вы можете захотеть раскошелиться и использовать его в качестве основы.   -  person b_erb    schedule 19.06.2011
comment
Еще один отличный пример документации RESTful API: twilio.com/docs/api/rest/call< /а>   -  person Nikola Petkanski    schedule 11.02.2013
comment
статья о некоторых вариантах: apievangelist .com/2014/01/16/   -  person JasonS    schedule 03.07.2014

Ответы (4)


arrow_upward
8
arrow_downward

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

person Michael Zilbermann    schedule 11.02.2013
comment
Это в значительной степени то, что я искал. Спасибо :) - person Colin; 12.02.2013

arrow_upward
3
arrow_downward

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

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

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

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

person Darrel Miller    schedule 06.06.2011
comment
Я понимаю вашу точку зрения и не собираюсь спорить о семантике, например, en.wikipedia.org/wiki /Restful вводит в заблуждение. Лично я бы выделил RESTful-приложение и RESTful API как две разные сущности. Однако в интересах здравомыслия я обновлю свой вопрос, чтобы он был более конкретным! - person Colin; 06.06.2011
comment
-1: Догматические удары по практичности. REST API тоже нуждаются в документации. Какие коды состояния HTTP я должен получить для проверки? Как осуществляется аутентификация? Какой набор символов я должен использовать? Как выглядит полезная нагрузка? Являются ли какие-либо его части необязательными? Какие данные принимают отдельные компоненты? Вы отмечаете, что такие вещи, как семантика приложения, заслуживают документирования, но вы, кажется, отрицаете, что инструмент, который можно использовать для простого документирования, должен существовать, принимая вместо этого за то, что существование инструмента означает, что вы выбрали неправильное решение. - person Jesper; 11.02.2013
comment
@jesper Код состояния для проверки: 400. Аутентификация выполняется, однако заголовок www-authenticate говорит об этом. Либо тип носителя, либо отношение ссылки скажет вам, как выглядит полезная нагрузка. Набор символов? документы типа носителя. Дополнительные компоненты, документы типа носителя. Если инструмент может волшебным образом задокументировать это, то, скорее всего, вы получите документы, в которых говорится: GET /Customer для получения клиента. Что ИМХО на 100% избыточно. В системе RESTful обнаружение ресурсов должно быть динамическим, а не в документации. - person Darrel Miller; 11.02.2013
comment
@DarrelMiller: вы, должно быть, говорите о другом REST API. API Twitter документирует все это. Я полностью согласен с тем, что такая псевдодокументация совершенно бесполезна. Однако это был не первоначальный вопрос; это было то, как мне прикрепить обоснованную документацию к моему списку вызовов, который в контексте REST был бы списком ресурсов и разрешенных операций. REST не ограничивается HATEOAS, где ваши баллы гораздо более применимы. - person Jesper; 11.02.2013
comment
@Jesper REST не ограничивается HATEOAS. Очевидно, парень, который изобрел этот термин, не согласен: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven - person Darrel Miller; 11.02.2013
comment
@DarrelMiller: я знаю, что говорится в диссертации Роя Филдинга (и что говорит Рой Филдинг в целом). Я также знаю, что делает большинство используемых REST API. Я не говорю, что не с нетерпением жду его будущего, но оно еще не наступило, а тем временем нам всем приходится иметь дело с системами в нашем окружении, которые действительно существуют. - person Jesper; 11.02.2013

arrow_upward
0
arrow_downward

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

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

person Colin    schedule 23.06.2011
comment
какие-либо обновления по созданию этого инструмента? - person rtdp; 18.02.2012
comment
Я создал спецификации для инструмента и схему данных, но, к сожалению, еще не приступил к ее созданию. - person Colin; 07.03.2012

arrow_upward
0
arrow_downward

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

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

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

person Nikola Petkanski    schedule 11.02.2013