OpenAPI/Swagger视频存储接口含义及响应配置问题咨询

这份是遵循OpenAPI 3.0.2标准编写的视频存储服务接口定义，对应服务默认部署地址为http://localhost:8080，仅提供1个对外接口：

• 接口路径：GET /files/{fileid}
• 功能：根据路径参数里的fileid（文件ID，必填字符串类型），下载服务器上存储的对应视频文件
• 成功响应（状态码200）要求携带Content-Disposition响应头，支持返回MP4、MPEG两种格式的视频二进制内容

1. 返回内容是可直接播放的视频还是二进制字节数组？ #

这两个不是互斥的关系。
规范里明确标注返回内容格式是string(format: binary)，也就是视频文件的原始二进制字节流——这是所有文件在HTTP传输中的本质形式。只要你响应头配置正确，浏览器、Postman拿到这段字节流之后就能自动识别为视频，直接支持预览播放；如果响应头配错，哪怕字节内容完全正确，客户端也可能直接弹出下载框，不会触发预览。
不存在“返回可播放视频就不能是字节流”的说法，能不能直接播放看的是响应头，不是传输的内容形式。

2. responses里的video/mp4、video/mpeg是什么意思？必须设置对应的Content-Type头吗？ #

这两个是HTTP标准里的MIME媒体类型，代表这个接口有能力返回两种不同编码格式的视频：

• 返回MP4格式文件时，对应MIME类型是video/mp4
• 返回MPEG格式文件时，对应MIME类型是video/mpeg

你必须根据实际返回的文件格式，把响应的Content-Type头设置为对应的正确值，不能乱填成application/octet-stream这类通用二进制类型，否则客户端无法正确识别内容是视频，自然也没法直接播放。

3. Content-Disposition头要按什么规则配置？ #

这个头是用来告诉客户端如何处理返回的内容，规范只要求返回这个头，没有强制规则，你可以根据业务需求二选一：

• 如果希望客户端默认在线预览播放，配置为inline，可附带文件名参数，示例：Content-Disposition: inline; filename="myvideo.mp4"
• 如果希望客户端默认触发下载、保存到本地，配置为attachment，同样可带文件名参数，示例：Content-Disposition: attachment; filename="myvideo.mpg"
  注意附带的文件名后缀要和实际返回的视频格式匹配，避免客户端识别后缀出错。

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