Мне интересно, есть ли у кого-нибудь опыт или рекомендации для инструментов, которые могут использоваться для создания веб-страниц, которые документируют и позволяют вам играть с RESTful JSON API. Я думаю о чем-то вроде API разработчика Github или Google API Console.
Оглядываясь, я нашел swagger из Wordnik, который выглядит хорошо. Но мне интересно, есть ли что-то еще и что люди испытывают с помощью этих инструментов. Спасибо.
Есть что-то еще, например enunciate и I/O Docs.
И вот блог об этой теме: Автоматическая документация для API REST
Мне нравится Apiary. Все еще в движении, но выглядит неплохо.
вопрос довольно старый, но я считаю, что он по-прежнему актуальен. Я знаю о трех инструментах проектирования API:
Я лично считаю, что эти инструменты хороши для обмена документами API между членами относительно небольших групп разработчиков, где каждый разработчик знает о деталях, специфичных для конкретного проекта, и им буквально просто нужно знать, является ли это POST или PUT, какие имена полей результата JSON.
Нам нужно было иметь богатые и удобные функции управления контентом вместе с конкретными материалами REST, которые создавали бы красивые документы в различных форматах, таких как одностраничный html или pdf Мы не смогли найти достойное программное обеспечение, чтобы мы решили создать Speca.io
В настоящий момент он находится в альфе и полностью свободен, но мы очень рады его воспроизвести, и любая обратная связь будет оценена.
Swagger может быть для вас. Он имеет реализации на разных языках.
Моя рекомендация - не слишком доверять генераторам [из исходного кода]. Я думаю, что публика документа - это, наконец, люди, и им нужно намного больше, чем могут предоставить WADL и файлы, созданные машиной. Чтобы помочь инструментам, вам нужно потратить время и силы на освоение идолокаций инструмента.
Кроме того, существует реальное практическое ограничение того, сколько можно включить в исходный код API. Простое документирование имен и типов параметров не будет большой помощью (и завершено), а добавление запроса образца и ответа внутри исходного кода выглядит неплохо (хотя важная информация для конечных пользователей). Другая причина может быть просто эстетикой.
Twitter также поддерживает документы вручную, и это говорит о многом. ИМХО, лучшим вариантом было бы поддерживать документацию в некотором дружественном для человека формате и генерировать HTML/PDF и т.д.
Бесстыдный штекер
https://github.com/rjha/restdoc
Это всего лишь пара очень простых PHP-скриптов, которые читают API из файлов определения YAML и генерируют HTML. Не может хорошо масштабироваться для огромного API EBay, но для простых требований документации API это может быть способ.
Мы работаем над MireDot, который работает для Java/Jax-rs. Начальная настройка занимает менее 5 минут. Очень доступная базовая версия бесплатна.
rest-tool - это простой инструмент командной строки, написанный на JavaScript с использованием Node.js. Это позволяет создавать автономные проекты, которые обеспечивают документацию, эмуляцию и автоматическое тестирование API RESTful.
Вы можете создавать рабочие API за пару минут, которые действуют как DMZ между разработчиками интерфейса и бэкэнд.
Он генерирует документацию, тестовые примеры и даже динамическую логическую логику на стороне сервера на основе шаблонов, поэтому все можно настраивать.
Я только что создал рубиновый камень "calamum", который генерирует html rest api doc, прост в использовании. https://github.com/malachheb/calamum.
Я только что создал Swadl, генератор документации WADL, вдохновленный swagger.
В принципе, интеграция вообще отсутствует - просто передайте ей свой wadl и создайте страницу.
Посмотрите здесь: https://github.com/ehearty/Swadl
И посмотрите здесь демо: http://ehearty.github.io/Swadl/wadl.html
Мне нравится обратная связь на моем инструменте
Мы работаем над продуктом под названием http://apiengine.io для решения этой проблемы