Fosrestbundle: Генерация документации REST API из маршрутов

Просмотрите скринкаст http://getfrapi.com/ , чтобы найти вдохновение.

Я это уже видел. Но мне многое не нравится в их реализации. Во-первых, их REST не RESTful :-D

"вдохновение", и я имел в виду не их отдых, а их документальное (и тестовое) поколение :)

Лично мне это не нравится, но не могли бы мы обсудить генерацию документации в формате WADL?

http://www.w3.org/Submission/wadl/

Интересно, было бы лучшим направлением, чем генерация, предоставить некоторые помощники представлений, которые позволили бы быстро создавать контроллеры/представления документации. Это кажется лучше, чем просто создание структуры, и будет более расширяемым/поддерживаемым. Другими словами, я думаю, что генерация документов API отлично подходит для варианта использования FRAPI (переход в приложение), но вопрос, нужна ли нам эта функция «как есть» или она вообще имеет смысл.

Мы говорим о документации для клиентов?

Имейте в виду, это то, чего REST пытается избежать:)

Одино: конечно. но есть такие вещи, как тот факт, что даже если вы следуете HATEAOS, вам нужно проверять заголовки. также, хотя вы должны знать, что следует ожидать разных кодов состояния, все же полезно знать, какие коды состояния «более вероятны». это просто удобно для случайного обзора API.

также еще одна тема, которую следует игнорировать: некоторым клиентам просто нравится убивать деревья, и приятно не тратить много времени на заполнение этих страниц бумаги :)

согласен, единственное, чего нам следует избегать, так это сильно полагаться на сгенерированную документацию, иначе мы будем копировать WSDL

палец вниз для убийц деревьев :)

Насколько я знаю, настоящие документы REST API посвящены определению типов мультимедиа и их отношений, а не URL-адресов. Например, http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

Но для простых API-интерфейсов HTTP, которые будут использоваться в 80% веб-проектов, эта функция все равно будет полезна.

Да, владарь, шаблоны URI явно злые. Но если нам нужно разработать пакет REST, мы должны следовать этим принципам.

Шаблон URI хорошо подходит для ApiBundle.

Возможно, вы сможете взять концепции с http://swagger.wordnik.com/

:+1: к чванству. Это выглядит потрясающе!

Чтобы создать аналогичный опыт, мы могли бы:

• Методы анализа, помеченные как @apidoc или что-то в этом роде
• Получить описание метода и параметры из docblock для методов с пометкой @apidoc
• Разрешить встроенное тестирование вызовов для каждого действия.

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

Другим вариантом было бы просто генерировать JSON, который потребляет Swagger, но имеет некоторый вес (Java)... Скорее бы увидеть «подобную» реализацию.

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

@pminnieur кажется, что мы могли бы так же легко предоставить ту же базовую функциональность, а не интегрировать.

По крайней мере, это могло бы работать как https://github.com/FriendsOfSymfony/FOSJsRoutingBundle — просто добавив немного причудливого HTML/CSS и предоставив свои маршруты RESTful с какой-то документацией API. Возможно, мы могли бы использовать некоторые аннотации для поддержки дополнительной информации.

Я хотел бы начать с этого, но я думаю, что было бы лучше поместить код в специальный пакет (например, FOSRestAPIExplorerBundle). Вопрос в том, будем ли мы поддерживать только Swagger API (поэтому Swagger используется для визуализации информации, собранной и представленной в формате JSON) или мы также предоставим собственный веб-интерфейс?

отдельный Bundle звучит как хорошая идея. если мы поддерживаем только чванство, мы могли бы указать это в названии пакета. Я не знаю, хотим ли мы также поддержать что-то еще. зависит от вашей мотивации и качества чванства. один вопрос о чванстве: как это работает с внутренними API, которые никто не хочет предоставлять внешней службе?

Я думаю, вам просто нужно не делать общедоступным URL-адрес, возвращающий Swagger JSON, если вы не хотите, чтобы он был общедоступным ... : D Серьезно, я бы хотел использовать аннотации, и если вы не хотите, чтобы маршрут был public, вы не добавите аннотацию @Expose() или @Expose(false) — что-то вроде этого. Точно так же, как FOSJsRoutingBundle настраивается, как с ним работать (открывать все по умолчанию или выставлять белый список). Если вы имеете в виду «вот ссылка на наш общедоступный API, и эта ссылка предназначена только для вас», мы можем добавить аннотацию, например @Api("public") и @Api("private") , включая компонент безопасности, чтобы вы могли раздавать разные API. документации разным людям (и контролировать доступ к ним).

Что касается имени: я хотел бы иметь общее имя, Swagger будет первой службой документации API, которая будет поддерживаться. Если люди хотят добавить какую-либо другую услугу, они могут просто это сделать (и не должны начинать с нуля). Например, @odino может добавить поддержку WADL. По крайней мере, я хотел бы также предоставить веб-интерфейс.

На данный момент я создал репозиторий GitHub для сбора идей и проблем, прежде чем мы начнем. Не стесняйтесь открывать темы для обсуждения любых вопросов или тем для обсуждения (имя также может быть обсуждено, конечно) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

хорошо. как только все сложится .. мы можем переместить его в FOS

Планируете ли вы использовать https://github.com/wordnik/swagger-ui в качестве «дисплея»?

во первых да. генерировать только json, соответствующий swagger-spec, который будет использоваться swagger-ui.

закрытие в пользу https://github.com/nelmio/NelmioApiDocBundle

Я знаю, что это очень старо, но с тех пор некоторые вещи изменились, и я нашел это относительно быстро, когда искал пакет/связку для Swagger/Openapi.
Есть шанс пересмотреть это? Поскольку NelmioApiDocBundle заброшен, и я не вижу реальной альтернативы, которая интегрируется в Symfony для Swagger/OpenApi (или любого другого, действительно, RAML, ...?).