В это обзоре мы поработаем над созданием 5 общих разделов документации API ссылки:
- описание ресурса;
- конечные точки и методы;
- параметры;
- примеры запроса;
- примеры и схема ответа
Чтобы обеспечить некоторый контекст (и продолжить наш пример сценария документации), мы разберем информацию из раздела Документирование новой конечной точки по этим пяти разделам.
5 Общих разделов в документации API
Карта рабочего процесса описания
Почти все API содержат описание пяти разделов:
В данном случае «Ресурсы» относятся к информации, возвращаемой API.
Конечные точки указывают, как получить доступ к ресурсу, а метод указывает разрешенные взаимодействия (такие как GET, POST или DELETE) с ресурсом.
Параметрами являются данные, которые можно передать конечной точке (например, указать формат ответа или возвращаемую сумму), чтобы повлиять на ответ.
Пример запроса включает в себя простой пример использования конечной точки, показывающий какие-то настроенные параметры.
Пример ответа показывает простой пример ответа из примера запроса; Схема ответа определяет все возможные элементы в ответе.
Ниже наскоро сделанная карта рабочего процесса, чтобы помочь сориентироваться на каждом шаге.
| Шаг 1. Описание ресурса |-->| Шаг 2. Конечные точки и методы |-->| Шаг 3. Параметры |-->| Шаг 4. Пример запроса|-->| Шаг 5. Пример и схема ответа |
Когда мы закончим, конечный результат будет выглядеть как настоящее описание раздела API (см. Готовый результат в разделе Собираем все вместе). На практических занятиях у нас будет возможность редактировать или создавать описание API в выбранном опен-сорс проекте.
Хотя существуют автоматические способы публикации документации API, в этой главе мы сосредоточимся на содержании, а не на инструментах. В следующем модуле, Спецификация OpenAPI и Swagger, мы рассмотрим, как описать те же самые компоненты, используя спецификацию OpenAPI. В модуле Публикация документации по API мы рассмотрим способы публикации информации.
Теперь, поскольку идея описания у нас есть, Вперед! к Шагу 1. Описание ресурса