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

phpDocumentor, по-видимому, является стандартом для документирования кода PHP, хотя мне нужно задаться вопросом, почему он не обновлялся годами.?

Однако он не подходит для документирования точек входа для REST API; IE, внешние точки входа, которые будут интересовать конечный пользователь вашей системы, в отличие от документирования всех внутренних классов и т.д., Что представляет интерес только для разработчиков api.

Я ищу что-то, где мог бы сказать, что этот метод здесь доступен извне через REST по этому URL-адресу, здесь нужны аргументы GET или POST, он поддерживает методы GET/POST/etc HTTP, возвращает JSON или XML или что-то еще.

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

ОТВЕТЫ

Ответ 2

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 должны использовать атрибут JSON-Schema links.

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

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 соответствует аналогичным принципам, но не обладает некоторыми функциями автоматического обнаружения.

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

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

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

Ответ 3

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

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

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

побочный продукт: это работает отлично с фасадами; Я использую фасад и factory много в моих конечных точках, а парсер 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 mobile phone number */

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

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

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

Ответ 4

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

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

Ответ 5

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

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

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

Что касается создания unit test, 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/

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