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

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

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

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

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

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

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

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

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

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