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

Question

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

80

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

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

aumanets 22 апр. 2011, в 18:16

Источник

12

Как я вижу, нет ничего плохого в том, чтобы задавать подобные вопросы. Из положительных отзывов, а также из очевидных полезных ответов ясно, что это очень хороший вопрос. Ответы всегда самоуверенны. Простое закрытие вопросов просто потому, что можно, не помогает полезности этого сайта, на мой взгляд.
QVSJ 21 май 2016, в 12:24

Теги:

indexing

rest

api

1 ответ

Ещё вопросы

Как я вижу, нет ничего плохого в том, чтобы задавать подобные вопросы. Из положительных отзывов, а также из очевидных полезных ответов ясно, что это очень хороший вопрос. Ответы всегда самоуверенны. Простое закрытие вопросов просто потому, что можно, не помогает полезности этого сайта, на мой взгляд.

Igor Kroitor · Answer 1 · 2017-07-03T19-47-00.000Z

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

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

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

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

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

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