Стандартные методы документирования API RESTful

Ответ 1

В Roy post здесь он утверждает

API REST должен тратить почти все его описательное усилие в определении тип мультимедиа, используемые для представления ресурсов и приложения для вождения состояния или определения расширенных имена отношений и/или гипертекстовая разметка для существующих стандартные типы носителей. Любые усилия описание способов использования URI, представляющие интерес, должны быть полностью определенных в рамках правила обработки для типа носителя (и, в большинстве случаев, уже определены существующими типами носителей).

Ответ 2

Конечно, API REST в идеале должен использовать HATEOAS и быть гипертекстовым (с интенсивным использованием типов медиа), но также иметь простые человеко- дружественная документация для разработчиков, чтобы отработать. Полезно.

Некоторые специальные инструменты, которые полезны для создания документации следующим образом:

• Swagger
  • Открытая спецификация для описания API REST [github]
  • Инструменты для автогенерации
    • Документация
    • Код для вашего API
• Mashery
  • Проект с открытым исходным кодом [github]
  • Инструменты для генерации
    • Документация
    • Интерфейс поиска для вашего API
• Apiary и API Blueprint
  • Напишите описание API в DSL в пределах уценки
  • Инструменты для автогенерации
    • Документация
    • Mock server
  • Кажется, что он сфокусирован на ruby ​​+ mac devs
• RAML
  • Спецификация для описания API REST [github]
• WADL
  • Спецификация для записи открываемых API-документов с XML
  • Некоторая дискуссия сравнение WSDL и WADL
• APIgee
  • Коммерческий продукт с некоторыми функциями документации
• 3scale
  • Коммерческий продукт с некоторыми функциями документации
• miredot
  • Коммерческий генератор документации API REST
  • Специфичные для Java

Ответ 3

Я использовал http://apiary.io, что довольно приятно. Вы также можете экспортировать документацию API в github.

Ответ 4

Хорошая документация REST будет означать документирование вашего типа носителя и только ваш тип носителя.

В типичном сценарии вы создадите такой документ:

Форматы XML Acme Corp

Обнаружение ссылок

Ссылки на различные ресурсы описаны в документе, который может быть найден путем выдачи запроса GET или HEAD серверу в URI закладки (обычно это корень сервера, http://www.acme.org) и поиск заголовка HTTP-ссылки:

Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml

где часть rel - это связь связи, а xxx - это URI, для которого установлено отношение.

Связи связей

В этом документе определяются следующие имена отношений:

• http://rel.acme.org/services Ссылка на ссылку описывает список ссылок, которые можно перемещать.
• http://rel.acme.org/customers Ссылка, для которой используется эта связь, - это список клиентов.

Типы носителей

application/vnd.acme.services+xml - это документ с сериализацией xml, который описывает список ссылок, которые приложение может захотеть обработать.

<links>
 <link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>

applcation/vnd.acme.customers+xml - это документ с сериализацией xml, описывающий клиентов.

Примеры документов:

<customers>
 <customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>

и т.д...

Цель состоит в том, чтобы дать разработчику возможность отслеживать ссылки, которые вы определяете. Сначала найдите ссылку на индекс, чтобы они могли получить список вещей, к которым они могут перейти.

Как только они обнаруживают этот документ, они обнаруживают, что они могут видеть список клиентов в определенном Uri и могут сделать GET против него.

Если они найдут интересующего клиента, они могут следовать ссылке, определенной в /customers/customer/@href, и выпустить GET для получения представления этого клиента.

Оттуда ваш тип носителя может вставлять действия, доступные пользователю, используя дополнительные ссылки. У вас также есть дополнительная возможность выдавать запрос OPTIONS на ресурсе, чтобы узнать, можете ли вы разрешить удаление ресурса или PUT, если вы можете сохранить документ после изменения.

Так хорошая документация никогда не была:

• предоставлять статические ссылки
• дает взаимодействие, такое как "вы можете выдать POST на Клиенте с этим типом носителя, и это будет означать операцию перемещения". Клиент должен выдать POST против Клиента только потому, что ваш XML-документ указал его таким образом.

Цель всего этого - добиться минимальной связи между клиентами и серверами. Клиент может быть очень умным в отображении и обнаружении ресурсов (показывая формы, а бог знает, что еще), но совершенно невзрачен в отношении того, что представляет собой рабочий процесс: сервер решает.

Ответ 5

В моей компании мы очень довольны использованием WADL, языка описания веб-приложений. Wikipedia описывает его как: "формат на основе XML, который обеспечивает машиночитаемое описание веб-приложений на основе HTTP". Я нахожу, что raw WADL легко писать, читать и понимать, и он напрямую сопоставляется с концепциями RESTful. Официальный проект предоставляет простые спецификации, схемы XSD и RELAX NG и инструменты Java.

Существует множество инструментов и ресурсов для работы с WADL, включая:

• wadl_stylesheets, таблицы стилей XSLT для создания документации HTML из файлов WADL
• Restlet, структура Java для создания серверов и клиентов RESTful включает расширение WADL

Совет: попробуйте включить в документ WADL document doc документ, читаемый человеком, например описания, концепции, начало работы, советы по использованию и т.д., включая HTML-элементы, используя пространство имен XHTML. Это может иметь большое значение!

Ответ 6

Изначально мы пошли на статическую документацию по ресурсам, но мне просто пришлось задать слишком много вопросов. В конце концов мы перешли на использование страниц Live-документации, используя IO/Docs (фактически fork). Работал отлично.

Ответ 7

Вы можете найти rest-tool.

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

Службы, которые вы только что описали, могут быть немедленно использованы, поэтому также полезно экспериментировать.

Ответ 8

Чтобы создать понимание/документацию, решения для тяжеловесов не всегда нужны. Примеры (больших) тяжелых инструментов: IO/Docs/Apigee (хотя и отличные инструменты).

Для крошечных проектов, которые уже имеют настройку docchain (doxygen/phpdoc/phpdoctor/custom/etc), я использую следующий shellscript, чтобы просто включить страницу в полную сгенерированную документацию:

https://gist.github.com/4496972

Демонстрация: http://pastie.org/5657190

Он просто использует пользовательские теги комментариев в вашем исходном коде. Это также может быть хорошей отправной точкой для документирования любого исходного кода (языка).