Автоматическое документирование REST API в PHP

Я знаю о 3 интеграции PHP с swagger:

• Swagger PHP composer

• Swagger PHP Symfony bundle

• Restler 3.0

Все должно помочь автоматически создать спецификацию swagger-spec, которая дает вам доступ от swagger-ui. Затем вы можете создавать api-клиенты и т. Д.

API RESTful должен полностью распознаваться и автоматически документироваться. Вам нужен только URL-адрес, и все, что связано с ним, должно описывать себя. Звучит как утопия, но это возможно.

Например, давайте начнем с URL-адреса образца, подобный stackoverflow: http://restfuloverflow.com (иллюстративный)

Первое, что вы делаете на ресурсе RESTful, – это запрос OPTIONS. Вам всегда нужно включить заголовок Accept, чтобы дать серверу ответ на самый подходящий тип mime:

OPTIONS * HTTP/1.1 Accept: text/html, text/xml, application/json Host: restfuloverflow.com 

Сервер должен проинструктировать клиента о том, что можно сделать по этому URL-адресу:

 HTTP/1.1 200 Ok Allow: GET, POST, PUT, DELETE, OPTIONS, TRACE, PATCH 

Это API RESTful, который говорит вам, что эта служба поддерживает эти методы. Первый, который вы попробуете, – это что-то вроде запроса ниже. Пользователь, попавший в API с браузером, должен работать аналогичным образом.

 GET / HTTP/1.1 Accept: text/html, text/xml, application/json Host: restfuloverflow.com 

Затем сервер должен вернуть некоторые ссылки, указывающие на связанные ресурсы, если они доступны:

 HTTP/1.1 200 Ok Content-Type: text/xml <?xml version="1.0"> <qa> <link href="/questions" title="Questions"/> <link href="/tags" title="Tags"/> <link href="/users" title="Users"/> </qa> 

HTML-версия должна использовать ссылки <a> , а ответы JSON должны использовать атрибут links JSON-Schema.

Скажем, клиент теперь решает, что он хочет знать, что делать с вопросами:

 OPTIONS /questions HTTP/1.1 Host: restfuloverflow.com Accept: text/html, text/xml, application/json 

Возможным ответом может быть:

 HTTP/1.1 200 Ok Allow: GET, POST Content-Type: text/xml <?xml version="1.0"> <xsd:element name="question"> <!-- XML Schema describing a question --> </xsd:element> 

Ну, сервер сказал нам, что можно задать и задать новый вопрос. Он также рассказал нам, как выглядит вопрос в XML, предоставляя XML-схему. JSON-SCHEMA может быть предоставлена ​​для JSON, и в HTML может быть предоставлена ​​форма для новых вопросов.

Предположим, пользователь хочет задать вопросы:

 GET /questions HTTP/1.1 Host: restfuloverflow.com Accept: text/html, text/xml, application/json 

Затем сервер отвечает:

 HTTP/1.1 200 Ok Content-Type: text/xml <?xml version="1.0"> <questions> <link href="/questions/intersting" title="Intersting Questions"/> <link href="/questions/hot" title="Hot Questions"/> </questions> 

Теперь все снова связано. Вещь продолжает идти таким образом, что сервис описывает себя. API Netflix следует аналогичным принципам, но не обладает некоторыми функциями автоматического обнаружения.

Этот API правительства Бразилии описывает себя с использованием RDF. Это один из лучших образцов RESTful, которые я когда-либо видел. Попробуйте изменить .rdf на .xml, .json или .html. (Это все на португальском, извините за это).

Лучшим инструментом для RESTful API в PHP является Respect \ Rest . Он имеет большую часть рабочего процесса, описанного здесь, уже загруженного, и появляются новые функции (он все еще находится в версии 0.4x).

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

Я нашел большой пакет узлов с именем apidoc, который выполняет огромную работу в DOC-RESTfuls. Он позволяет использовать множество тегов, специфичных для API, с параметрами и т. Д., Но то, что действительно продало меня, это его сгенерированные тестовые формы in-doc для каждого метода.

Я использую его в проекте скелета devops на https://github.com/ardkevin84/devops.skel.php-with-docs-metrics , но вы можете увидеть фактический вывод в моем проекте aplo callloop на https://github.com /ardkevin84/api.callloop . Индекс apidoc: build / api-docs / apidoc / index.html

Единственный недостаток, если он один, заключается в том, что он – естественно – принимает свои собственные докблоки. Однако он не сталкивается с «родными» Docblocks. Блоки apidoc не должны предшествовать методу, поэтому я обычно группирую их вместе в верхней части моего файла конечной точки, где другие механизмы doc не связывают их с классом doc.

Побочный продукт: это отлично работает с фасадами; Я много использую фасад и фабрику в своих конечных точках, а парсер apidoc позволяет мне обрабатывать условия фасада отдельно. В приведенном ниже примере «подписка», «отказ от подписки» и «триггер» обрабатываются одной точкой входа, но они документируются отдельно.

Пример: этот Docblock

/** * @api {get} ?action=:action&first=:firstname&last=:lastname&email=:useremail&phone=:phone&gid=:groupid Subscribe * @apiSampleRequest http://www.example.com/rest/callloop.php * @apiName Subscribe * @apiGroup Subscription * @apiDescription subscribes a user to the provided group * @apiParam {string="subscribe","unsubscribe","trigger"} action=subscribe API Action to call. For subscriptions, use "subscribe" * @apiParam {String} [first] Optional first name * @apiParam {String} [last] Optional last name * @apiParam {String} [email] Optional user email * @apiParam {String} phone User's mobile phone number */

требуется для генерации этого результата, в комплекте с тестовой формой

важно, если вы используете стандартный $ _GET с параметрами запроса . Пакет, установленный с узла, не поддерживает точки enpoint, такие как service.php?param=value , но в git repo на запрос https://github.com есть запрос на перенос / apidoc / apidoc / pull / 189, в котором рассматривается это. Это базовое решение для шаблона по умолчанию. Я закрепил несколько строк в моем пакете узлов и работает как шарм.

бесстыдная самореклама: это, вероятно, гораздо проще в использовании при автоматическом сборке. Посмотрите мой проект devops выше для kickstart;) Он разветвлен от jenkins-php, но добавляет в несколько doc-движков и цели-заглушки для таких вещей, как нажатие сгенерированных документов \ metrics на путь localhost и выпуск упаковки для выпуска (zip, tar и т. Д.). )

Swagger кажется многообещающим, но это потребует, чтобы ваш API проявил себя совместимым образом … это довольно приятно, однако, с тестовой консолью и т. Д. Все встроенные … вы можете загрузить версию javascript и запустить ее на своем сервере наряду с php api.

EDIT: вот ссылка, это не так легко найти в google, если у вас нет полного имени … lol … Swagger-UI: https://github.com/wordnik/swagger-ui

Самый простой способ – использовать токенизатор / парсер docblock. Есть несколько из них (я скоро закрою мои), но в основном они могут изучить docblock и обозначить любые пользовательские (или нестандартные) теги docblock. Я использую это внутри моей структуры, чтобы определить типы помощников вида через тег под названием «@helperType».

Как я уже сказал, их много, но вот мой, чтобы вы начали: https://github.com/masterexploder/DocumentingReflectionMethod

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

Что касается создания тестовых тестов, PHPUnit может автоматически генерировать их из ваших классов (проверьте их документы для получения дополнительной информации: http://www.phpunit.de/manual/3.5/en/skeleton-generator.html#skeleton-generator.test

Вы также можете использовать phpdocumenter для анализа ваших собственных тегов: http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.customtags

Наконец, есть одна структура (я знаю, я уверен, что есть тонны), которая использует аннотации, чтобы делать всевозможные успокоительные качества (возможно, сэкономив себе некоторую работу): http://www.recessframework.org/

Надеюсь, это поможет!