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

Я пишу спецификацию для RESTful API для новой внутренней веб-службы. Это не очень долго и довольно просто, но даже так, это мой первый раз, когда я использую строгий отдых (в отличие от обмана по практическим причинам - избегая PUT и DELETE потому что они боль в PHP, и так далее). Мне было интересно, существуют ли какие-либо стандартные методы или рекомендации для документирования интерфейса REST? Я хочу, чтобы остальная часть команды поняла это с первого взгляда, и для всех, кто хочет написать клиент, чтобы иметь возможность сделать это без понимания базового кода.

8 52
database-restore documentation

8 ответов:

в должности здесь Он

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

9

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

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

  • чванство
    • открытая спецификация для описания API REST [ github]
    • инструменты для автоматическое создание
      • документация
      • код для вашего API
    • пожертвовал на инициативу OpenAPI и переименован в OpenAPI в 2015 году
  • Mashery
    • проект с открытым исходным кодом [ github]
    • инструменты для генерации
      • документация
      • интерфейс исследования для вашего API
  • пасеке и API Blueprint
    • напишите описание API в DSL в пределах markdown
    • инструменты для автоматической генерации
      • документация
      • макет сервера
    • кажется, сосредоточены на ruby + mac devs
  • RAML
    • спецификация для описания API REST [ github]
  • WADL
    • спецификация для написания обнаруживаемых документов API с XML
    • обсуждение сравнение WSDL и WADL
  • APIgee
    • коммерческий продукт с некоторыми функциями документации
  • 3scale
    • коммерческий продукт с документацией особенности
  • miredot
    • Commercial REST API documentation generator
    • Java specific
39

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

13

хорошая документация 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 Ссылка, для которой используется эта связь, - это список клиентов.

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

The 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>

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

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

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

etc...

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

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

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

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

так что хорошая документация не:

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

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

6

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

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

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

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

4

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

2

вы можете найти rest-tool полезное.

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

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

2

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

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

https://gist.github.com/4496972

демо: http://pastie.org/5657190

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

0