Портал документации к API Selectel
Камилла Гарифуллина
Руководитель отдела знаний

Мы выпустили публично доступный портал с документацией к 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 до нашего корпоративного стиля.

Заключение

Портал документации к API доступен для работы с начала августа. Постепенно мы будем добавлять документацию к API других наших сервисов.

Если у вас есть идеи или предложения по улучшению справочного центра, пишите на почту kb@selectel.ru.

Что еще почитать по теме

Андрей Зайцев 8 сентября 2021

Продуктовый дайджест: новые серверы, Selectel Connect и обновления «Облачной платформы»

У нас обновления в конфигурациях серверов, кластерах Kubernetes и разделах базы знаний. А еще обратите внимание на сервис Selectel Connect. В конце дайджеста — анонс конференции по ML и записи митапов…
Андрей Зайцев 8 сентября 2021
Ульяна Малышева 11 августа 2021

Продуктовый дайджест: автомасштабирование в Managed Kubernetes и две услуги в бете

Запустили две услуги в бете — «Файловое хранилище» и «Бэкапы по расписанию», реализовали автомасштабирование нод в Managed Kubernetes, а также добавили возможность арендовать виртуальные серверы с гар…
Ульяна Малышева 11 августа 2021
Ульяна Малышева 7 июля 2021

Продуктовый дайджест: новые процессоры AMD EPYC™ и управление базами данных через Terraform

Пополнение линейки процессоров AMD EPYC™, управление кластерами «Облачных баз данных» через Terraform-провайдер Selectel и подбор идеальной инфраструктуры под «Битрикс24» и «1С-Битрикс». Подробнее — о…
Ульяна Малышева 7 июля 2021
Ульяна Малышева 18 июня 2021

Selectel развернул 100 виртуальных машин для олимпиады «Я — профессионал»

Завершился четвертый сезон олимпиады «Я — профессионал», на который зарегистрировались 576 012 студентов из 348 вузов России. Selectel стал одним из партнеров трека олимпиады «Робототехника», который …
Ульяна Малышева 18 июня 2021
Ульяна Малышева 9 июня 2021

Продуктовый дайджест: бессерверные вычисления для «Облачного хранилища» и аренда лицензий NVIDIA

Запустили новую зону доступности облачных сервисов, дали клиентам выделенных серверов возможность узнать расположение их инфраструктуры в стойках и открыли бесплатный курс по Managed Kubernetes. Подро…
Ульяна Малышева 9 июня 2021

Новое в блоге

bondar 24 сентября 2021

Piller CPM300: зачем мы устанавливаем новые динамические ИБП

Бесперебойная подача электропитания в серверные — одна из обязательств провайдера дата-центра перед клиентами. Но важна не только отказоустойчивость решения, но и его эффективность с точки потребления…
bondar 24 сентября 2021
Владимир Туров 18 сентября 2021

Разбираем редкого зверя от Nvidia — DGX A100

Крупные IT-компании располагают дорогими «игрушками», которые скрыты от взоров большинства пользователей. Сегодня мы приоткроем завесу тайны и расскажем про систему, которая оптимизирована для работы …
Владимир Туров 18 сентября 2021
Андрей Зайцев 8 сентября 2021

Продуктовый дайджест: новые серверы, Selectel Connect и обновления «Облачной платформы»

У нас обновления в конфигурациях серверов, кластерах Kubernetes и разделах базы знаний. А еще обратите внимание на сервис Selectel Connect. В конце дайджеста — анонс конференции по ML и записи митапов…
Андрей Зайцев 8 сентября 2021
Ульяна Малышева 12 августа 2021

RHVoice Lab: как серверы помогают создавать голоса для синтезаторов речи

В этом году Selectel стал поддерживать некоммерческий проект RHVoice Lab — лабораторию по созданию новых голосов для одноименного отечественного синтезатора речи. Его особенность в том, что синтезатор…
Ульяна Малышева 12 августа 2021