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

Question

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

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

Answer 1

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

Возможно, вы захотите взглянуть на существующие структуры API, такие как Swagger Спецификация ( 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

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

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

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