Edit me

После завершения Обзора пошагового описания API мы готовы к практике, которая даст нам больше опыта в создании и редактировании документации по API. В этой практике мы и покритикуем и создадим свой собственный раздел API для опен-сорс проекта, выбранный нами ранее.

👨‍💻 Оценка ключевых элементов API документации

Практическое занятие позволит рассмотреть документацию API и определить общие элементы. Для оценки документации:

  • Оцениваем документацию API, ответив на следующие вопросы для каждого раздела:
    • Описание ресурса
      • является ли описание action-oriented?
      • краткое ли резюме (1-3 предложения)?
    • Конечные точки и методы
      • как сгруппированы конечные точки (на одной или нескольких страницах? Сгруппированы по методу или по ресурсу)?
      • как определены методы для каждой конечной точки?
    • Параметры
      • сколько параметров у конечной точки (заголовок, путь, строка запроса, параметры тела запроса)?
      • определены ли типы данных для каждого параметра (string, boolean, etc)? указаны мин/макс значения?
    • Примеры запроса
      • в каком формате или на каком языке показан запрос (curl, специфичный язык или другое)?
      • сколько параметров включает в себя пример запроса?
    • Примеры ответа
      • представлены ли ответ и схема ответа? актуально ли описание каждого элемента?
      • как сайт документации обрабатывает вложенные иерархии в определениях ответов

Создание или изменение раздела документации API

Эта часть задания может быть сложной, но здесь мы начнем создавать примеры для своего портфолио.

  1. В том же проекте определяем одну из тем API, которую нужно дополнить. (Если у API есть новая конечная точка без документации, можно сфокусироваться на этой конечной точке.);
  2. Заполняем раздел, чтобы улучшить его (Если это новая конечная точка, задокументируйте ее);
  3. Создаем Pull request и внесим свои изменения в проект.

Следующие шаги

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

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

Но перед тестированием неплохо бы ознакомиться и со спецификациями OpenAPI и Swagger

🔙

Go next ➡