Как сделать красивую документацию для Web API, за которую будет не стыдно

[lair]

А почему не Swagger?

[Dimones]

Мне показалось это более удобным вариантом и более красивым чем Swagger. В будущем я обращу внимание на Swagger.

[TerminusMKB]

Приятно, что кто-то думает и о красивости :)
Надоели решения «программисты для программистов».

[Dimones]

Спасибо за похвалу)

[centur]

А вас не смущает что внешняя красивость достигается через кучу кастомных тегов и описаний в коде? Почему никто не думает о читабельности кода? тот же Swagger — просто стандартный формат описания, из него можно и документацию сгенерить красивую (генераторов статичного красивого html — завались) так и сгенерить автоматический прокси для вызова этого api в коде.

Внизу уже упомянули что написание отдельной документации для каждого метода, помимо стандартной — утомляет. Это на самом деле — проблема в long-run. Когда проект только начинается — все радостно пишут документацию, когда ближе к окончанию, или даже через полгода — все уже начинают забивать на документацию. Хорошо еще если есть настрой написать стандартную доку, не говоря уже про специальную отдельную доку для генератора. В итоге — гладко было на бумаге…
Мне больше импонирует подход swagger (вернее разных пакетов генерящих swagger описание по коду) — выяснить максимум о коде и представить это в виде стандартного описания. А уж пользователь-разработчик сам решит что ему генерить — красивую документацию или прокси или CRUD интерфейс.

[Jabher]

А чем Swagger лучше RAML, что вы его рекомендуете? Про Blueprint от Apiary молчу — его трудно любить

[lair]

RAML мне не нравится тем, что он contract-first. Мне больше импонирует написать сервер и получить от него (всегда актуальную) документацию автоматически.

[lowadka]

А я вот люблю, перешел со Swagger`а

[Jabher]

Blueprint как стандарт на самом деле не очень плох (если не считать того, что парсер только на сях, что ограничивает сферу применения — на клиенте просто так не поредактируешь без кросскомпиляции, что тоже не очень хорошо), но вот сам апиари реализует его совершенно отвратительно. Более того, то, что у них крутится — отвратительно устаревшее решение, которое не поддерживает огромное количество нужных фич из него же.
Нет ни авторизации, ни простановки заголовков, ни даже таких банальных вещей, как поддержка переменных в пути — /resource/{id}. Чтоб так с примером, валидацией и всем прочим.
Опять же, JSON Schema у них заявлена в поддержке, но в итоге ей и не пахнет даже толком.

Я как временное решение не так давно сделал свой обработчик и рендерер для их формата — с авторизацией и всем остальным (все почти строго по стандарту), но в итоге оказалось, что RAML писать куда приятнее.

[0leGG]

Например, тем, что Swagger может генерировать не только документацию, но также скелет API для сервера и полную клиентскую реализацию для ≈20 платформ.

[jackz]

Не увидел как описывать возвращаемые ошибки…

[Dimones]

Извините не дописал, ибо «тегов» много, а статья не должна была быть огромной. Посмотреть остальные «теги» в том числе и возвращаемые ошибки вы можете здесь здесь.

[jonic]

Пользовали, на нашем АПИ, исходники документации стали похожи на кашу. На самом деле, было бы возможно не плохо, если бы был инструмент который выглядит так же — но позволяет редактировать себя так же на лету. Есть такие?

[MikhailShel]

есть вот anypoint там есть возможность экспорта-импорта raml и просмотра на лету, но конечно нужен raml для начала.

[kondalex]

Интересно выглядит.
Но есть бага — понажимал кнопочки, получил результат, стал скроллить вниз и ускроллил менюшку слева. ;)

[fuzzy]

Не так давно использовал в одном своем проекте. Действительно удобно, хотя написание комментариев для apidoc утомляет. Между прочим, я так и не понял, как использовать версионность в apidoc, т.е. каким образом оно различает, что вот этот вариант — из версии 1.0, а этот — из версии 1.1? Посмотрел в Вашем примере — и все равно не понял. Можно какой-то реальный пример из жизни?

[WeslomPo]

Нужно создавать копию комментария с новой версией, старые комментарии переносить в отдельный документ (а можно и не переносить). Например сохранять все старые версии в файл "_apidoc.js". По имени и группе система находит записи и группирует разделяя по версиям. Немного спорный подход.

[Invision70]

При отправке запросов ошибка 500, печально

[tonymadbrain]

«Как сделать красивую документацию для Web API, за которую будет не стыдно» — руками. Как сказал наш архитектор: ересь это (имеется в виду статья) еще и на ноде, apiary и blueprint — тру!

[wAngel]

Ваш архитектор случайно не аргументировал свои слова?

[monolithed]

— Меню не рассчитано на большое количество методов (у нас например из почти 300)
— Для чего выводить все методы на одной странице?
— Отсутствует поиск
— Отсутствуют страницы с описанием методов, ответов, форматов, ответственных лиц и пр. (иногда даже требуется отобразить схему взаимодействий)
— Нет аннотации/списка всех методов
— Отсутствуют возможность работы с несколькими проектами
— Формат запросов и ответов (кстати там 500, вместо моков) очень спорный. На сколько я понимаю он не учитывает вложения (аля JSON структура)
— Как насчет наследования (многие методы могу иметь идентичный набор полей)?

[dumistoklus]

Да вот про поиск и наследование было очень интересно узнать

[monolithed]

+ многие забывают о возможности экспорта моков. Это нужно для того чтобы фронтенд-разработчик не ждал реализацию метода, а вместо этого уже писал код фичи.

[MrFrizzy]

Если кто живет на readthedocs — помимо дефолтного sphinx + rest есть еще pdoc + markdown. Оригинальный автор, правда, забил, но форки живут потихоньку…

[monolithed]

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

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