Комментарии 25
А почему не Swagger?
Мне показалось это более удобным вариантом и более красивым чем Swagger. В будущем я обращу внимание на Swagger.
Приятно, что кто-то думает и о красивости :)
Надоели решения «программисты для программистов».
Надоели решения «программисты для программистов».
Спасибо за похвалу)
А вас не смущает что внешняя красивость достигается через кучу кастомных тегов и описаний в коде? Почему никто не думает о читабельности кода? тот же Swagger — просто стандартный формат описания, из него можно и документацию сгенерить красивую (генераторов статичного красивого html — завались) так и сгенерить автоматический прокси для вызова этого api в коде.
Внизу уже упомянули что написание отдельной документации для каждого метода, помимо стандартной — утомляет. Это на самом деле — проблема в long-run. Когда проект только начинается — все радостно пишут документацию, когда ближе к окончанию, или даже через полгода — все уже начинают забивать на документацию. Хорошо еще если есть настрой написать стандартную доку, не говоря уже про специальную отдельную доку для генератора. В итоге — гладко было на бумаге…
Мне больше импонирует подход swagger (вернее разных пакетов генерящих swagger описание по коду) — выяснить максимум о коде и представить это в виде стандартного описания. А уж пользователь-разработчик сам решит что ему генерить — красивую документацию или прокси или CRUD интерфейс.
Внизу уже упомянули что написание отдельной документации для каждого метода, помимо стандартной — утомляет. Это на самом деле — проблема в long-run. Когда проект только начинается — все радостно пишут документацию, когда ближе к окончанию, или даже через полгода — все уже начинают забивать на документацию. Хорошо еще если есть настрой написать стандартную доку, не говоря уже про специальную отдельную доку для генератора. В итоге — гладко было на бумаге…
Мне больше импонирует подход swagger (вернее разных пакетов генерящих swagger описание по коду) — выяснить максимум о коде и представить это в виде стандартного описания. А уж пользователь-разработчик сам решит что ему генерить — красивую документацию или прокси или CRUD интерфейс.
А чем Swagger лучше RAML, что вы его рекомендуете? Про Blueprint от Apiary молчу — его трудно любить
RAML мне не нравится тем, что он contract-first. Мне больше импонирует написать сервер и получить от него (всегда актуальную) документацию автоматически.
А я вот люблю, перешел со Swagger`а
Blueprint как стандарт на самом деле не очень плох (если не считать того, что парсер только на сях, что ограничивает сферу применения — на клиенте просто так не поредактируешь без кросскомпиляции, что тоже не очень хорошо), но вот сам апиари реализует его совершенно отвратительно. Более того, то, что у них крутится — отвратительно устаревшее решение, которое не поддерживает огромное количество нужных фич из него же.
Нет ни авторизации, ни простановки заголовков, ни даже таких банальных вещей, как поддержка переменных в пути — /resource/{id}. Чтоб так с примером, валидацией и всем прочим.
Опять же, JSON Schema у них заявлена в поддержке, но в итоге ей и не пахнет даже толком.
Я как временное решение не так давно сделал свой обработчик и рендерер для их формата — с авторизацией и всем остальным (все почти строго по стандарту), но в итоге оказалось, что RAML писать куда приятнее.
Нет ни авторизации, ни простановки заголовков, ни даже таких банальных вещей, как поддержка переменных в пути — /resource/{id}. Чтоб так с примером, валидацией и всем прочим.
Опять же, JSON Schema у них заявлена в поддержке, но в итоге ей и не пахнет даже толком.
Я как временное решение не так давно сделал свой обработчик и рендерер для их формата — с авторизацией и всем остальным (все почти строго по стандарту), но в итоге оказалось, что RAML писать куда приятнее.
Например, тем, что Swagger может генерировать не только документацию, но также скелет API для сервера и полную клиентскую реализацию для ≈20 платформ.
Не увидел как описывать возвращаемые ошибки…
Извините не дописал, ибо «тегов» много, а статья не должна была быть огромной. Посмотреть остальные «теги» в том числе и возвращаемые ошибки вы можете здесь здесь.
Пользовали, на нашем АПИ, исходники документации стали похожи на кашу. На самом деле, было бы возможно не плохо, если бы был инструмент который выглядит так же — но позволяет редактировать себя так же на лету. Есть такие?
есть вот anypoint там есть возможность экспорта-импорта raml и просмотра на лету, но конечно нужен raml для начала.
Интересно выглядит.
Но есть бага — понажимал кнопочки, получил результат, стал скроллить вниз и ускроллил менюшку слева. ;)
Но есть бага — понажимал кнопочки, получил результат, стал скроллить вниз и ускроллил менюшку слева. ;)
Не так давно использовал в одном своем проекте. Действительно удобно, хотя написание комментариев для apidoc утомляет. Между прочим, я так и не понял, как использовать версионность в apidoc, т.е. каким образом оно различает, что вот этот вариант — из версии 1.0, а этот — из версии 1.1? Посмотрел в Вашем примере — и все равно не понял. Можно какой-то реальный пример из жизни?
При отправке запросов ошибка 500, печально
«Как сделать красивую документацию для Web API, за которую будет не стыдно» — руками. Как сказал наш архитектор: ересь это (имеется в виду статья) еще и на ноде, apiary и blueprint — тру!
— Меню не рассчитано на большое количество методов (у нас например из почти 300)
— Для чего выводить все методы на одной странице?
— Отсутствует поиск
— Отсутствуют страницы с описанием методов, ответов, форматов, ответственных лиц и пр. (иногда даже требуется отобразить схему взаимодействий)
— Нет аннотации/списка всех методов
— Отсутствуют возможность работы с несколькими проектами
— Формат запросов и ответов (кстати там 500, вместо моков) очень спорный. На сколько я понимаю он не учитывает вложения (аля JSON структура)
— Как насчет наследования (многие методы могу иметь идентичный набор полей)?
— Для чего выводить все методы на одной странице?
— Отсутствует поиск
— Отсутствуют страницы с описанием методов, ответов, форматов, ответственных лиц и пр. (иногда даже требуется отобразить схему взаимодействий)
— Нет аннотации/списка всех методов
— Отсутствуют возможность работы с несколькими проектами
— Формат запросов и ответов (кстати там 500, вместо моков) очень спорный. На сколько я понимаю он не учитывает вложения (аля JSON структура)
— Как насчет наследования (многие методы могу иметь идентичный набор полей)?
Если кто живет на readthedocs — помимо дефолтного sphinx + rest есть еще pdoc + markdown. Оригинальный автор, правда, забил, но форки живут потихоньку…
На самом деле, сейчас очень много интересных решений, у которых можно либо что-то перенять либо просто использовать «коробочную» версию.
Навскидку:
apiblueprint.org
apiary.io
www.mashape.com
developer.klout.com/io-docs
apigee.com/about
www.miredot.com
apispark.com
raml.org
github.com/danielgtaylor/aglio
Навскидку:
apiblueprint.org
apiary.io
www.mashape.com
developer.klout.com/io-docs
apigee.com/about
www.miredot.com
apispark.com
raml.org
github.com/danielgtaylor/aglio
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Как сделать красивую документацию для Web API, за которую будет не стыдно