OpenApi：如何描述错误代码和消息？

Question

我想为我的错误 400 提供一系列自定义代码和消息，但找不到任何方法来执行此操作。理想情况下是这样的：

Error:
  type: object
  enum:
    - [E01, 'Error1']
    - [E02, 'Error2']

等等

Answer 1

所以我不确定这里的枚举可以帮助你。如果您查看官方文档，枚举只是字符串，而不是对象https://swagger.io/docs/specification/data-models/enums/。

所以我的建议是使用：

ErrorType:
 type: object
 properties:
   code: 
     type: integer
   name:
     type: string
 example:   # Sample object
     code: 10
     name: Custom Error

 Error:
  type: object
  properties:
     errors:
       oneOf:
         - $ref '#/ErrorType'
         - etc...
or directly without properties
Error:
  type: object
  oneOf:
   - $ref '#/ErrorType'
   - etc...

您可以在官方页面上查看更多示例https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/