После завершения Обзора пошагового описания API мы готовы к практике, которая даст нам больше опыта в создании и редактировании документации по API. В этой практике мы и покритикуем и создадим свой собственный раздел API для опен-сорс проекта, выбранный нами ранее.
Оценка ключевых элементов API документации
Создание или изменение раздела документации API
Практическое занятие позволит рассмотреть документацию API и определить общие элементы. Для оценки документации:
- В списке 100 сайтов с API документацией или из полученного на прошлом практическом занятии результата выбираем сайт или несколько сайтов с API документацией
- На каждом сайте ищем раздел документации API со списком конечных точек
- В документации по каждой ссылке находим информацию:
Названия разделов могут отличаться на разных сайтах API-документации, но обычно они легко узнаваемы.
- Оцениваем документацию API, ответив на следующие вопросы для каждого раздела:
- Описание ресурса
- является ли описание action-oriented?
- краткое ли резюме (1-3 предложения)?
- Конечные точки и методы
- как сгруппированы конечные точки (на одной или нескольких страницах? Сгруппированы по методу или по ресурсу)?
- как определены методы для каждой конечной точки?
- Параметры
- сколько параметров у конечной точки (заголовок, путь, строка запроса, параметры тела запроса)?
- определены ли типы данных для каждого параметра (string, boolean, etc)? указаны мин/макс значения?
- Примеры запроса
- в каком формате или на каком языке показан запрос (curl, специфичный язык или другое)?
- сколько параметров включает в себя пример запроса?
- Примеры ответа
- представлены ли ответ и схема ответа? актуально ли описание каждого элемента?
- как сайт документации обрабатывает вложенные иерархии в определениях ответов
Эта часть задания может быть сложной, но здесь мы начнем создавать примеры для своего портфолио.
- В том же проекте определяем одну из тем API, которую нужно дополнить. (Если у API есть новая конечная точка без документации, можно сфокусироваться на этой конечной точке.)
- Заполните раздел, чтобы улучшить его (Если это новая конечная точка, задокументируйте ее)
- Создайте Pull request и внесите свои изменения в проект
Теперь, когда мы с головой погрузились в API документацию, пришло время перейти к тестированию. Поскольку мы работаем с конечными точками API и другим кодом, нам нужно будет самостоятельно протестировать эти конечные точки, чтобы собрать и проверить информацию, содержащуюся в документации. Тестирование - не всегда простая штука, поэтому этой теме посвящен целый модуль. Переходим к обзору тестирования документации
Но перед тестированием неплохо бы ознакомиться и со спецификациями OpenAPI и Swagger