Портал документации к API Selectel

Камилла Гарифуллина Руководитель отдела знаний 18 августа 2020

Мы выпустили публично доступный портал с документацией к API наших продуктов и услуг. В этой статье мы расскажем, какой подход выбрали и как его реализовали. Каждой предоставляемой услугой Selectel можно управлять в личном кабинете — панели управления. Многими нашими продуктами также возможно управлять через запросы к API. Как обещали в статье База знаний 2.0, мы […]

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

Каждой предоставляемой услугой Selectel можно управлять в личном кабинете — панели управления. Многими нашими продуктами также возможно управлять через запросы к API. Как обещали в статье База знаний 2.0, мы собрали знания по автоматизации IT-инфраструктуры и взаимодействию с бэкендом сервисов Selectel на портале developers.selectel.ru.

Ранее полной и структурированной документации к API наших продуктов не было в открытом доступе. Часть была размещена в панели управления my.selectel.ru, что-то — выдавалось по запросу, а что-то было и вовсе описано в текстовом формате, поддерживать который в актуальном состоянии было весьма проблематично. Теперь инструкции по работе с продуктами и документация API доступны в едином справочном центре.

Немного об использовании API

Большинство компаний, производящих ПО, на определённом этапе разрабатывают API как для внутреннего использования, так и для клиентов. Компании делятся набором вводных параметров, выпуская публичные API для того, чтобы дать клиентам возможность объединять собственные сервисы и предлагаемые компанией продукты.

Многие пользовательские задачи можно автоматизировать, в том числе используя готовые куски кода как конструктор для создания максимально удобной в использовании инфраструктуры. Но куски кода без объяснений, что оно делает и как этим пользоваться — малополезны — не будешь ведь перебором выяснять, какие есть методы и какие данные они ожидают на вход.

— Что нужно сделать, чтобы публичным API было приятно пользоваться?
— Приложить документацию!

В качестве документации к API обычно дают минимальный пример взаимодействия, в котором описаны методы (также их называют эндпоинтами) и приведены ответы от сервиса. Например, с помощью API Kubernetes можно автоматизировать работу с кластерами и нодами в «Managed Kubernetes».

Какие задачи мы решали

Одной из проблем использования документации API, сгенерированной в OpenAPI, Swagger или с помощью другого инструмента генерации, является сложная интеграция с остальной частью сайта. Нужно, чтобы пользователи имели беспроблемный доступ ко всем инструкциям и статьям — неудобно, если эндпоинты отображаются в одном представлении, а текстовые описания тех же процессов — на другой странице.

При создании единого справочного центра нам надо было сохранить единообразие отображения инструкций и спецификаций, используя связку «git + markdown + swagger».

Как это работает теперь

Техническая реализация

Мы уже упоминали, что используем принцип docs-as-a-code для подготовки базы знаний по продуктам. Разработчики продуктов Selectel формируют API, и выгружают комментарии к коду в swagger-формате – это текстовый файл в формате YAML, с которым можно работать как с кодом. При обновлении API обновляется и swagger-файл, что позволяет упростить актуализацию документации.

Для портала документации API мы разработали следующее техническое решение:

git-репозиторий с файлами swagger-спецификаций в формате YAML, сгруппированными по продуктам;
git-репозиторий с переводами swagger-спецификаций в формате JSON;
git-репозиторий с файлами в формате MD;
файлы в формате MD содержат текстовые описания и «‎обернутые»‎ в специальные теги описания эндпоинтов, которые подтягиваются из git-репозитория с файлами в формате JSON;
генератор статических сайтов Hugo.

Кроме структуры репозитория были разработаны правила работы с ним:

подготовлен стайлгайд – чек-лист для swagger-файлов, с которым сверяются разработчики при обновлении спецификаций API;
ветвь master git-репозитория с файлами в формате MD отражает состояние актуальных спецификаций и де-факто находится на продакшене;
pull-request в master-ветку осуществляется при выпуске обновлений в боевую эксплуатацию.

Визуальная составляющая

Каждая компания делает документацию API в соответствии с собственным видением стиля, структуры и чувства прекрасного. Если открыть 4-5 публичных API разных компаний, то, несомненно, мы сможем уловить некие общности: структура, объемные примеры кода и подсветка синтаксиса, длинные страницы, но, тем не менее, все примеры будут обладать своими особенностями.

Например, локализация описаний эндпоинтов встречается редко, несмотря на то, что как раз структура описания эндпоинтов чаще всего выглядит одинаково.

Несколько рекомендаций к структурированию документации API:

Группировка эндпоинтов. Помимо предоставления информации для каждого эндпоинта, если эндпоинтов много — желательно группировать их. Длинный сплошной список эндпоинтов затрудняет навигацию.

Отдельное описание методов. При одновременном использовании методов GET/POST — в одной строчке должен быть описан только один метод. То есть первой строчкой в этом случае идет описание GET, второй строчкой — описание POST, благодаря чему можно избежать путаницы.

Автоматизация внесения изменений. Упростить внесение изменений без ручного переформатирования каждого раздела — в нашем случае мы переводим только текст swagger-файла, не трогая разметку благодаря автоматизации этого процесса, который настроили наши devops-специалисты.

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

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

Так как «из коробки» была доступна подсветка кода только для темного фона, frontend-разработчик дорабатывала это решение с помощью highlight.js до нашего корпоративного стиля.