Структурирование онлайн-документации для REST API

Я создаю свой первый API-интерфейс Rest, который преобразует данные в формат JSON и XML. Я хотел бы предоставить индексную страницу для клиентов API, где они смогут выбирать реализованные конечные точки.

Какую информацию мне нужно включить, чтобы сделать мой API наиболее полезным и как его организовать?

ОТВЕТЫ

Ответ 1

Это очень сложный вопрос для простого ответа.

Вы можете взглянуть на существующие рамки API, например Swagger Спецификация (OpenAPI) и сервисы, такие как apiary.io и apiblueprint.org.

Кроме того, здесь приведен пример одного и того же REST API, организованного и даже стилизованного тремя способами. Это может быть хорошим началом для вас, чтобы учиться на существующих общих путях.

На самом верхнем уровне я считаю, что для качественных документов REST API требуется, по крайней мере, следующее:

  • список всех ваших конечных точек API (базовые/относительные URL-адреса)
  • соответствующий тип метода HTTP GET/POST/... для каждой конечной точки
  • запрос/ответ MIME-тип (как кодировать параметры и ответы на парсы)
  • пример запроса/ответа, включая заголовки HTTP
  • тип и формат, указанные для всех параметров, в том числе в URL, теге и заголовках
  • краткое текстовое описание и важные примечания
  • короткий фрагмент кода, показывающий использование конечной точки в популярных языках веб-программирования.

Также существует множество основанных на JSON/XML-инфраструктур документов, которые могут анализировать ваше определение или схему API и создавать для вас удобный набор документов. Но выбор для системы генерации doc зависит от вашего проекта, языка, среды разработки и многих других.