Документирование определения кодов ошибок в контракте Swagger API - PullRequest
Новая
       59

Документирование определения кодов ошибок в контракте Swagger API

1 голос
/ 14 марта 2019

Представьте, что вы работаете в следующих обстоятельствах:

  • У вас есть REST API-модули с документацией API, сгенерированной в swagger-ui.html
  • Возможные коды состояния HTTP для конечных точек хорошо документированы с помощью io.swagger.annotations.* на уровне метода контроллера для каждой конечной точки.

  • В случае некоторого состояния ошибки (4XX или 5XX) приложение отвечает ErrorResponseDTO со структурой, подобной 

    "ErrorResponseDTO": {
  "type": "object",
  "properties": {
     "errorCode": {
       "type": "integer",
       "format": "int32"
     },
    "message": {
      "type": "string"
    }
  }
}

  • Приложение имеет десятки кодов ошибок (в пределах диапазона, например 1 - XX , и, пожалуйста, рассматривайте их как устаревшее определение без простого способа их изменения).

  • Список кодов ошибок актуален для всего приложения, поэтому вы предпочитаете хранить их список / таблицу определений в общей документации API, а не сохранять определение кодов ошибок для каждой конечной точки API отдельно.

Теперь вы ищете эффективный способ документирования этих кодов ошибок приложения в контракте API.

Подход включения списка сгенерированных кодов ошибок с описанием кодов в swagger-ui.html кажется лучшим способом обновления документации API, вместо того, чтобы прикреплять таблицу определения статических и рукописных кодов в формате Markdown в каком-то файле Readme.

Не могли бы вы порекомендовать, как документировать различные коды, создаваемые вашими приложениями?

Следуете ли вы какой-то конкретной хорошей практике в этой теме?

Заранее спасибо.

...