记录Swagger API合约中的错误代码定义

Question

假设您在以下情况下工作：

• 您拥有REST API模块，其API文档已生成到swagger-ui.html
中
• 可以通过io.swagger.annotations.*在每个端点的控制器方法级别上很好地记录端点的可能HTTP状态代码。

• 在出现某些错误状态（4XX或5XX）的情况下，应用程序会使用ErrorResponseDTO答复结构类似

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

• 应用程序有数十个错误代码（在 1-XX 之类的范围内，请将其视为传统定义，而没有简单的更改方法）。

• errorCodes列表与整个应用程序相关，因此您宁愿将它们的定义列表/表保留在整个API文档中，而不是分别为每个API端点维护errorCodes定义。

现在，您正在寻找一种有效的方法来将这些应用程序错误代码记录到API合同中。

在生成的swagger-ui.html中包含错误代码列表和代码描述的方法似乎是使API文档保持最新状态的更好方法，而不是在某些自述文件中以Markdown格式附加静态和手写代码定义表

请问您对如何记录应用程序产生的各种代码有何建议？

您是否遵循本主题中的一些特定的良好做法？

谢谢。