如何在OpenAPI中标记REST API可重试响应码并支持Swagger UI？

1. 规范层面的自定义扩展方案 #

OpenAPI本身没有内置的可重试响应码标记，但允许通过**x-前缀的自定义扩展字段**实现，这是社区通用的标准做法。你可以直接在响应码的定义中添加x-retryable属性，示例如下：

paths:
  /api/resource:
    get:
      responses:
        429:
          description: 请求过于频繁
          x-retryable: true
        503:
          description: 服务不可用
          x-retryable: true
        200:
          description: 请求成功
          x-retryable: false

所有以x-开头的字段都是OpenAPI规范认可的自定义扩展，能被各类工具（如API网关、客户端生成器）识别和处理。

2. Swagger UI的支持方式 #

Swagger UI默认不会展示自定义扩展字段，需要通过以下两种方式实现可视化：

• 编写自定义插件：用JavaScript编写简单插件，遍历响应定义读取x-retryable属性，在UI中添加醒目标记（比如橙色的“可重试”标签）。
• 修改前端代码：直接调整Swagger UI的渲染逻辑，在响应码区域自动展示可重试状态标识。

此外，OpenAPI Generator等工具也能读取这类扩展字段，自动生成带重试逻辑的客户端代码。

3. 类比Kafka协议错误的复用式实现 #

参考Kafka协议错误的分类思路，你可以把可重试响应统一抽象到components节中复用，让API规范更整洁：

components:
  responses:
    Retryable429:
      description: 请求过于频繁
      x-retryable: true
      headers:
        Retry-After:
          schema:
            type: integer
    Retryable503:
      description: 服务不可用
      x-retryable: true

paths:
  /api/resource:
    get:
      responses:
        '429':
          $ref: '#/components/responses/Retryable429'
        '503':
          $ref: '#/components/responses/Retryable503'

内容的提问来源于stack exchange，提问作者nik0x1