В каком сценарии Slate и Swagger будут использоваться вместе? - PullRequest
1 голос
/ 26 мая 2019

Из этого вопроса Я видел, что

Swagger и Slate служат двум различным целям.Swagger - это попытка стандартизированного способа описания RESTful API.

Сланец, с другой стороны, является симпатичной темой для написания хороших документов по API.

Далее говорится, что

Оба не являются взаимоисключающимиВ идеале, вы должны сгенерировать вашу документацию по грифу из описания вашего Swagger API

Я немного запутался.Зачем мне нужен шифер, если у меня уже есть Swagger UI , вот так .

Что еще мне нужно для «документирования»?Я искренне спрашиваю, потому что, как я уже сказал, я немного смущен их использованием.

1 Ответ

1 голос
/ 26 мая 2019

Есть несколько вещей, о которых стоит упомянуть при создании документации для нового API.

Swagger предоставляет действительно хороший графический интерфейс для исследования конечных точек API, но есть и другие вещи, которые должны быть включены в вашу документацию, включая (но не ограничиваясь):

  1. Методы аутентификации (OAuth / JWT, Basic Auth, Cookie / Session, Apikey / token)
  2. Форматы даты для вывода даты + часовой пояс
  3. Параметры фильтрации / разбиения на страницы / выбора / сортировки для API
  4. Какие существуют среды (обычно тестовые, предварительные и производственные), включая их различия.
  5. Обработка ошибок, включая коды ошибок, типы исключений и ведение журнала
  6. Потенциальные ограничения по ставке для вашего API
  7. Условия использования вашего API
...