OpenAPI 规范 v3.1.0
OpenAPI 规范 v3.1.0
1. OpenAPI 规范
2. 简介
3. 定义
4. 规范
4.1 版本
4.2 格式
4.3 文档结构
4.4 数据类型
4.5 富文本格式化
4.6 URI 中的相对引用
4.7 URL 中的相对引用
4.8 模式
4.9 规范扩展
4.10 安全过滤
4.8.16 Responses 对象
创建时间: 2025-05-29 16:38

操作预期响应的容器。该容器将 HTTP 响应代码映射到预期响应。文档不一定需要涵盖所有可能的 HTTP 响应代码,因为它们可能事先未知。但是,文档需要涵盖成功操作响应和任何已知错误。default可以用作未由 Responses Object 单独涵盖的所有 HTTP 代码的默认响应对象。Responses Object必须包含至少一个响应代码,如果仅提供一个响应代码,则应该是成功操作调用的响应。

4.8.16.1 固定字段
字段名称类型描述
default响应对象  引用对象除为特定 HTTP 响应代码声明的响应之外的响应文档。使用此字段来涵盖未声明的响应。
4.8.16.2 模式化字段
字段模式类型描述
HTTP 状态代码响应对象  引用对象任何 HTTP 状态代码 都可以用作属性名称,但每个代码只有一个属性,以描述该 HTTP 状态代码的预期响应。为了在 JSON 和 YAML 之间兼容,此字段必须用引号括起来(例如,“200”)。要定义一系列响应代码,此字段可以包含大写通配符 X。例如,2XX 表示 [200-299] 之间的所有响应代码。仅允许以下范围定义:1XX2XX3XX4XX 和 5XX。如果使用显式代码定义了响应,则该显式代码定义优先于该代码的范围定义。**

此对象*可以使用 规范扩展 进行扩展。

4.8.16.3 Responses 对象示例

成功操作的 200 响应以及其他响应的默认响应(暗示错误)

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}
'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'
最后更新: -