Edit me

В этом обзоре мы поработаем над созданием 5 общих разделов документации API ссылки:

  • описание ресурса;
  • конечные точки и методы;
  • параметры;
  • примеры запроса;
  • примеры и схема ответа

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

5 общих разделов в документации API

Почти все API содержат описание пяти разделов:

1. Описание ресурса

В данном случае «Ресурсы» относятся к информации, возвращаемой API.

2. Конечные точки и методы

Конечные точки указывают, как получить доступ к ресурсу, а метод указывает разрешенные взаимодействия (такие как GET, POST или DELETE) с ресурсом.

3. Параметры

Параметрами являются данные, которые можно передать конечной точке (например, указать формат ответа или возвращаемую сумму), чтобы повлиять на ответ.

4. Пример запроса

Пример запроса включает в себя простой пример использования конечной точки, показывающий какие-то настроенные параметры.

5. Пример и схема ответа

Пример ответа показывает простой пример ответа из примера запроса; Схема ответа определяет все возможные элементы в ответе.

Карта рабочего процесса описания

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

Шаг 1. Описание ресурса > Шаг 2. Конечные точки и методы > Шаг 3. Параметры > Шаг 4. Пример запроса > Шаг 5. Пример и схема ответа

После описания

Когда мы закончим, конечный результат будет выглядеть как настоящее описание раздела API (см. Готовый результат в разделе Собираем все вместе). На практических занятиях у нас будет возможность редактировать или создавать описание API в выбранном опен-сорс проекте.

Дальнейшие шаги

Теперь, поскольку идея описания у нас есть, Вперед, к Шагу 1. Описание ресурса!

🔙

Go next ➡