Как стать автором
Обновить

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

Время на прочтение 4 мин
Количество просмотров 52K

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

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

Рецепт салата
Рецепт салата

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

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

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

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

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

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

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

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

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

Product Owner

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

Разработчик

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

Тестировщик

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

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

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

Product owner

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

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

Разработчик

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

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

Тестировщик

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

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

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

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

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

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

Документы могут быть слишком подробными (слева), но выполнять задачу проще по-понятному (справа).
Документы могут быть слишком подробными (слева), но выполнять задачу проще по-понятному (справа).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

История изменений
История изменений

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

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

Примеры запроса и ответа
Примеры запроса и ответа

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

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

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

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

Проверки

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

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

Проверки входных параметров
Проверки входных параметров

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

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

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

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

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

Описание интеграции
Схема работы метода по добавлению записи о животном
Схема работы метода по добавлению записи о животном

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

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

Интеграции

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

Например, если бы метод POST /pet пошел бы в следующую систему для сохранения информации о животном.

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

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

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

Только зарегистрированные пользователи могут участвовать в опросе. Войдите, пожалуйста.
Чем пользуетесь для написания документации?
65.67% Confluence 132
27.86% Word 56
13.93% Jira 28
6.97% Notion 14
4.48% Корпоративные программы 9
16.92% Другое 34
1.99% Asscidocs 4
Проголосовал 201 пользователь. Воздержался 31 пользователь.
Теги:
Хабы:
+4
Комментарии 11
Комментарии Комментарии 11

Публикации

Истории

Работа

Ближайшие события

Московский туристический хакатон
Дата 23 марта – 7 апреля
Место
Москва Онлайн
Геймтон «DatsEdenSpace» от DatsTeam
Дата 5 – 6 апреля
Время 17:00 – 20:00
Место
Онлайн