Swagger docs - 单个 http 响应的多个错误代码

Posted 2023-02-19

【中文标题】Swagger docs - 单个 http 响应的多个错误代码

【英文标题】：Swagger docs - multiple error codes for a single http response

【发布时间】：2020-11-17 05:55:54

【问题描述】：

我正在尝试记录一个始终返回自定义响应代码和相关描述的模型。对于单个 HTTP 响应代码，可能有多个自定义响应代码。例如，400 响应可能包括：

+===========+======+=============+
| HTTP Code | Code | Description |
+===========+======+=============+
|       400 |    1 | Error 1     |
+-----------+------+-------------+
|       400 |    2 | Error 2     |
+-----------+------+-------------+
|       400 |    3 | Error 3     |
+-----------+------+-------------+

我可以记录 400 状态返回具有“代码”和“描述”的“错误”对象。但如果可能的话，我想在文档中包含所有自定义状态代码。可能吗？如果是这样，我该怎么做？

【问题讨论】：

你在找这个吗？看看批准的答案以及***.com/questions/36576447/…

我不认为这是我正在寻找的东西，除非我必须为每个自定义状态代码记录单独的模式。我基本上需要为每个http状态码指定多个示例

在 Swagger yaml 中使用 openapi 3.0 让我使用多个示例，几乎可以让我做我想做的事，而无需大量额外工作。唯一的问题是……我所有的回复都是 XML 格式的。为了提供无法用 JSON 表示的多个示例，您必须将 XML 放入字符串文字中。我真的很想避免这样做。

【参考方案1】：

对于现在面临这个问题的任何人，这是我能够解决的方法：

              '422':
                description: 'Unprocessable Entity'
                content:
                    application/json:
                        schema:
                          oneOf:
                            - $ref: '#/components/schemas/SchemaForErrror1'
                            - $ref: '#/components/schemas/SchemaForErrror2'

                        examples:
                          Error1:
                            $ref: '#/components/examples/ExampleForError1'
                          Error2:
                            $ref: '#/components/examples/ExampleForError2'