«Как я перестал волноваться и стал отдавать метаданные restful API»

Дневник ру

Дневник.ру – лидер в сфере технологий дистанционного образования России: покрывает более 82% реального рынка и 39% потенциального. Мы предоставляем школам единую образовательную платформу, сочетающую в себе три модуля: обучение, управление школой и социальную сеть. С нами более 27 000 школ в 83 регионах России.

Расскажите друзьям
Дневник ру
Дневник ру

Если вы делаете публичный API, то скорее всего сталкивались с проблемой его документации. Большие компанииделают специальные порталы для разработчиков, где можно почитать и обсудить документацию, или скачать библиотеку-клиент для вашего любимого языка программирования.

Поддержка такого ресурса (особенно в условиях, когда API активно развивается) — достаточно трудозатратное дело. При изменениях, приходится синхронизировать документацию с фактической реализацией и это напрягает. Синхронизация состоит из:

  • Проверки, что вся существующая функциональность описана в документации
  • Проверки, что всё описанное работает как заявлено в документации

Автоматизировать второй пункт предлагают ребята из стартапа apiary.io, они предоставляют возможность написать документацию на специальном предметно-ориентированном языке (DSL), а потом, при помощи прокси к вашему API, записать запросы, и периодически проверять, что всё, описанное соответствует действительности. Но в данном случае, вам всё ещё придется самим писать всю документацию, и это кажется лишним, потому что интерфейс вы, скорее всего, уже описали в коде.

Конечно же, универсального способа извлечь интерфейс в виде описания запросов и ответов из кода не существует, но если вы используете фреймворк, в котором есть соглашения по поводу маршрутизации и выполнения запросов, то такую информацию можно получить. Кроме того, существует мнение, что такое описание не нужно и клиент должен сам понять, как работать с REST API, зная только URL корневого ресурса и используемые media types. Но я не видел ни одного серьёзного публичного API, которое использует такой подход. 

Чтобы автоматически сгенерировать документацию, понадобится формат для описания метаданных, что-то вродеWSDL, но с описаниями в терминах REST.

Есть несколько вариантов: читайте продолжение в нашем блоге http://habrahabr.ru/company/dnevnik_ru/blog/174555/


Комментарии

Комментарии могут оставлять только авторизованные пользователи.
Web Summit 2017
6 ноября 2017
Ещё события


Telegram канал @rusbase