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

Question

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

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

Я ищучто-то, что я мог бы сказать: эй, этот метод здесь доступен извне через REST по этому URL, здесь приведены аргументы GET или POST, он принимает методы HTTP GET / POST / etc, он возвращает JSON или XML или любой другой.1006 * Эта информация сможет создать документ API.Он также может использоваться внутренним кодом для автоматической фильтрации входных данных, проверки выходных данных, создания базовых модульных тестов и т. Д.

Answer 1

Мне известны 3 PHP-интеграции с Swagger:

• Swagger PHP composer

• Swagger PHPПакет Symfony

• Рестлер 3,0

Все должно помочь автоматически создать Swagger-Spec, который даетВы получаете доступ от Swagger-UI.Затем вы можете генерировать API-клиенты и т. Д.

Answer 2

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

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

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

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

Пример: этот докблок

/**
 * @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 с параметрами запроса: Пакет, установленный из узла, не поддерживает такие точки, как service.php?param=value, но в git-репозитории есть запрос на извлечение в https://github.com/apidoc/apidoc/pull/189, который обращается к этому. Это базовое исправление шаблона по умолчанию. Я пропатчил несколько строк в свой пакет узлов, и он работает как шарм.

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

Answer 3

RESTful API должен быть полностью обнаруживаемым и автоматически документироваться.Вам нужен только 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-Атрибут Схема 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>

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

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

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

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

Answer 4

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

РЕДАКТИРОВАТЬ: вот ссылка, это не так легко найти в Google, если у вас нет полного имени ... LOL ... Swagger-UI: https://github.com/wordnik/swagger-ui

Answer 5

Самое простое, что можно сделать - это использовать токенайзер / парсер докблока. Есть несколько из них (я скоро напишу о них), но в основном они могут проверять докблок и маркировать любые пользовательские (или нестандартные) теги докблока. Я использую это в моей структуре для определения вспомогательных типов представления с помощью тега "@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

Наконец, есть один фреймворк (который я знаю, я уверен, что есть тонны), который использует аннотации для выполнения всевозможных спокойных дел (возможно, спасая себя от работы): https://github.com/recess/recess

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