allOf:组合多个 schema,例如合并对象或扩展基础 schema。作用类似于and运算符。anyOf:接受与任一给定 schema 匹配的数据。作用类似于or运算符。oneOf:接受恰好与一个给定 schema 匹配的数据。作用类似于exclusive-or运算符。
oneOf 和 anyOf 的处理方式相同,并且不支持 not 关键字。有关这些关键字的详细规范,请参阅 OpenAPI 文档中的 oneOf, anyOf, allOf, not。
当你使用 allOf 组合两个对象 schema 时,Mintlify 会将两者的属性合并到一个对象中。这在使用 OpenAPI 可复用的组件时非常有用。
oneOf 或 anyOf 时,各选项会显示在带标签页的容器中。在每个子 schema 中指定 title 字段来命名标签页。例如,你可以这样显示两种不同类型的收货地址:
any 或 undefined 的字段与 oneOf schema 的渲染方式相同,会提供一个选择器,让用户在发送请求前选择具体的结构。
在 OpenAPI 3.1 中,你可以使用 if、then、else、dependentRequired 和 dependentSchemas 关键字,使某个属性仅在特定情况下必填。Mintlify 会读取这些关键字,并在端点页面上为每个受影响的字段标注 required 标记及其条件。
例如,此 schema 要求银行卡支付提供卡号,其他所有支付方式提供账号,并且在请求包含税号时提供公司名称:
card_number:当method=card时必填account_number:除非method=card,否则必填company_name:当设置了tax_id时必填
const 或 enum 测试同级属性特定值、或使用 required 测试其是否存在的条件,Mintlify 会进行概括。如果条件过于复杂而无法概括,该字段会改为显示 conditionally required 标记。
对于 OpenAPI 3.1 和 3.2 规范,请将文件上传定义为带有二进制 contentMediaType 的 string schema。API 试验台会将该字段显示为文件输入框,并作为 multipart/form-data 请求的一部分发送。
application/octet-stream、图片、音频、视频、PDF 和压缩包。试验台不会将 application/json 等结构化媒体类型视为文件上传。
使用 contentEncoding 描述文件内容的编码方式。对于 base64 编码的文件,将 contentEncoding 设置为 base64 或 base64url,试验台会将该字段视为 base64 文件。对于其他值或未设置值的情况,试验台使用二进制文件处理方式。没有二进制 contentMediaType 的 contentEncoding 值仍然是文本字段。
旧的 format: "binary" 和 format: "base64" 值仍然受支持。
如果你的 API 会根据输入参数、用户上下文或请求的其他条件返回不同的响应,请使用响应上的 examples 属性逐一记录。
Content-Type header 渲染响应:
- 图片(
image/*):内联渲染。 - 音频(
audio/*):使用音频播放器渲染。 - 视频(
video/*):使用视频播放器渲染。 - 所有其他响应:显示在代码块中。
audio/*,并使用音频文件的 URL 作为示例值:
text/event-stream、application/jsonl、application/x-ndjson、application/json-seq 和 multipart/mixed。请求体为 multipart/form-data 的请求不会以流式方式传输。
在响应流式传输期间,响应面板会显示 Streaming…,发送按钮会变为 Stop。点击 Stop 即可结束请求。试验台会保留已收到的数据并显示 Stream stopped。
试验台会以纯文本形式显示流式响应体,不进行 JSON 格式化。流也可能提前结束:
- 试验台在读取 10 MB 后停止读取,并显示 Stream truncated at 10 MB。
- 如果连接在流结束前关闭,试验台会显示 Stream interrupted。
- 当试验台代理开启时,你的 API 必须在 30 秒内发送响应 header,并且代理会在五分钟后结束该流。
paths 字段并列添加 webhooks 字段。有关定义 webhook 的更多信息,请参阅 OpenAPI 规范中的 Webhooks。
要为 webhook 创建 MDX 页面,请在 openapi frontmatter 中使用 webhook 代替 HTTP 方法:
webhooks 字段中的键完全一致。
回调描述了你的 API 向调用方提供的 URL 发送的带外请求,例如与特定操作关联的事件通知。当某个操作定义了 callbacks 时,端点页面会在请求体和响应部分之间的可折叠区域中显示它们。每个回调都会显示其 HTTP 方法和表达式,并使用与父操作相同的请求体和响应布局。
有关定义回调的更多信息,请参阅 OpenAPI 规范中的 Callback object。