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.8.1 OpenAPI 对象
4.8.2 Info 对象
4.8.3 Contact 对象
4.8.4 License 对象
4.8.5 Server 对象
4.8.6 Server Variable 对象
4.8.7 Components 对象
4.8.8 Paths 对象
4.8.9 Path Item 对象
4.8.10 Operation 对象
4.8.11 External Documentation 对象
4.8.12 Parameter 对象
4.8.13 Request Body 对象
4.8.14 Media Type 对象
4.8.15 Encoding 对象
4.8.16 Responses 对象
4.8.17 Response 对象
4.8.18 Callback 对象
4.8.19 Example 对象
4.8.20 Link 对象
4.8.21 Header 对象
4.8.22 Tag 对象
4.8.23 Reference 对象
4.8.24 Schema 对象
4.8.25 Discriminator 对象
4.8.26 XML 对象
4.8.27 Security Scheme 对象
4.8.28 OAuth Flows 对象
4.8.29 OAuth Flow 对象
4.8.30 Security Requirement 对象
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] 之间的所有响应代码。仅允许以下范围定义:1XX 、2XX 、3XX 、4XX 和 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'
最后更新: -