Удачный шаблон документации на API, который будут читать

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

Вы бы стали читать рецепт из 10 страниц, чтобы приготовить салат? Что-то я сомневаюсь. Схожая ситуация бывает в документации, когда она пишется без шаблона по принципу «чем больше, тем лучше».

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

Я тех. лид системных аналитиков и прошла долгий путь к шаблонам документации в разных компаниях.

С чего все начинается

Чаще всего у системного аналитика болит от того, что его техническое задание (ТЗ) не читают. Разрабатывают как поняли, тестируют как услышали, а заказчик ждет вообще другое. Еще болит, а как описать задание разработчику, если в компании нет шаблона?

Самое важное понять, кто и для чего будет пользоваться документацией.

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

Перед нами команда, которая разрабатывает новые интеграции.

Системный аналитик

Отвечает за документацию

Product Owner

Ставит задачи аналитику

Разработчик

Программирует

Тестировщик

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

Задача аналитика — описать интеграцию систем (спроектировать API).

Для чего команде документ

Product owner

В описании ищет ответы на вопросы:

Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?

Разработчик

Без документа не понимает как ему делать задачу, поэтому вопросы у него такие:

Что мне делать: параметры запроса-ответа?
В какие системы сходить за данными или передать?

Тестировщик

Прочитав описание интеграции, сможет ответить на вопросы:

Как бы это все сломать: какие ошибки можно сделать?
Где найти тестовые запрос-ответ?
С какими системами есть взаимодействие, чтобы проверить весь путь?

Аналитик другой команды

Этому человеку нужна любая документация, потому что у него один вопрос:

Как переиспользовать или доработать сервис, чтобы ничего не сломать?

Скорость разработки — это важное преимущество, потому что кто первый вышел на рынок с продуктом, тот и выиграл. Время на написание или чтение ТЗ выделяется мало, поэтому документ должен содержать необходимый и достаточный минимум для быстрой разработки.

Из чего состоит шаблон

В шаблоне на интеграцию (API) будут разделы:

Основная информация Запрос/Ответ Входные параметры    Проверки Выходные параметры    Положительный ответ    Ответ с ошибками Описание интеграции Интеграции    Интеграция с сервисом №1

Почему именно такая структура?

Спокойствие, только спокойствие, сейчас все расскажу!

Вспомните, у каждого участника команды были вопросы, мотивирующие его прочитать документацию. От них и отталкиваемся, поэтому такое содержание.

Основная информация

В разделе можно найти ответы на вопросы:

Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?

Запрос/Ответ, Входные и выходные параметры

В этих разделах документа есть информация:

Что мне делать: параметры запроса-ответа?
Где найти тестовые запрос-ответ?
Как бы это все сломать: какие ошибки можно сделать?

Описание интеграции

Здесь есть ответы на вопросы:

В какие системы сходить за данными или передать?
С какими системами есть взаимодействие, чтобы проверить весь путь?
Как переиспользовать или доработать сервис, чтобы ничего не сломать?

Как применить шаблон на практике

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

В шаблоне есть:

Основная информация

Раздел содержит таблицу, которая позволяет понять, о чем будет документ, и найти все ссылки в одном месте.

Автор — ФИО, кто пишет или правит документ
Задача — ссылка на задачу (например, JIRA) или описание задачи
Бизнес постановка — описание какую пользу приносит эта задача пользователям
Связанные документы — документы или ссылки с описанием, что в них находится

История изменений документа

Раздел содержит таблицу:

Версия — номер версии
Дата — дата в формате ДД.ММ.ГГГ
Автор — ФИО кто создал или изменил документ
Описание изменений — текстовое описание того, что вы добавили в документ.

Запрос/Ответ

Пример запроса и ответа для добавления информации о животном на сайте

Входные параметры

Раздел содержит таблицу:

Параметр — название параметра на английском
Тип данных — указать тип данных параметра с ограничениями по длине если они есть
Обязательность — да/нет
Описание — понятное описание для чего используется параметр
Варианты значений — перечислить варианты значений с пояснениями, для чего они используются или привести пример одного из значений

Проверки

Раздел содержит таблицу:

Параметр — название параметра на английском
Проверка — условие и результат проверки

Выходные параметры

 Положительный ответ

Параметры аналогичны входным

Ответ с ошибками

Описание интеграции

Для построения сервиса использовался инструмент plantuml. Работа с ним описана в статье https://habr.com/ru/post/661931/

Посмотреть реализованный сервис можно по ссылке https://petstore.swagger.io/#/pet/addPet. Для удобства описания были придуманы некоторые проверки и коды ошибок 🙂

Вы получили шаблон технической документации на API . Скачать шаблон google docs можно по ссылке

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

Возможно вам шаблон не подойдет, но вы всегда можете составить свой и поделиться им в комментариях.