如何在OpenAPI中定义json-lines格式的响应？

虽然JSON Lines暂时没有IANA官方注册的标准MIME类型，但是完全可以在OpenAPI规范中完成对这类响应的描述，无需粗暴定义为string类型丢失结构参考价值，具体方法如下：

• 首先指定对应MIME类型，行业内通用的非官方标准MIME类型有两个可选：application/x-ndjson、application/json-lines，直接在响应的content节点下声明该类型即可，不要使用默认的application/json。
• 该类型对应的schema直接定义为数组类型，数组的items字段就是你每行需要返回的单个JSON对象的结构，API规范使用者可以直观理解到每一行响应对应数组中的一个元素，和你原本要返回的对象数组结构完全对齐。

你可以参考以下示例写法：

openapi: 3.0.3
paths:
  /data-stream:
    get:
      responses:
        '200':
          description: 行分隔的JSON数据流，每行对应一个数据对象
          content:
            application/x-ndjson:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - create_time
                  properties:
                    id:
                      type: integer
                      format: int64
                    create_time:
                      type: string
                      format: date-time
                    content:
                      type: string

如果担心部分API调试工具对非标准MIME类型的兼容性不好，也可以同时保留普通application/json格式的数组响应定义，将JSON Lines格式作为可选响应补充即可。

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