如何在OpenAPI 3.0.3中拆分parameters至独立文件复用？

1. 拆分参数到独立文件 #

按照需求创建三个YAML文件，具体内容如下：

query.yaml（单独存放query参数）

name: query
in: query
description: ''
required: false
schema:
  type: string

pagination.yaml（存放分页相关的limit和offset参数）

- name: limit
  in: query
  description: ''
  required: false
  schema:
    type: integer
- name: offset
  in: query
  description: ''
  required: false
  schema:
    type: integer

query_with_pagination.yaml（组合query与分页参数）

直接整合前两个文件的参数，实现一次引用即可获取全部三个参数：

- $ref: './query.yaml'
- name: limit
  in: query
  description: ''
  required: false
  schema:
    type: integer
- name: offset
  in: query
  description: ''
  required: false
  schema:
    type: integer

注：如果你的OpenAPI工具支持直接引用参数数组，也可以写成以下形式（更简洁）：

- $ref: './query.yaml'
- $ref: './pagination.yaml'

2. 实际引用示例 #

• 仅需query参数的场景：

parameters:
  - $ref: '../../shared/parameters/query.yaml'

• 需要query+分页参数的场景：

parameters:
  - $ref: '../../shared/parameters/query_with_pagination.yaml'

关于allOf无效的原因 #

OpenAPI的allOf关键字仅适用于Schema对象（如请求体、响应体的结构定义），不能用于参数对象。参数本身必须是包含in、name等必填字段的独立对象，用allOf包裹后会破坏参数的结构要求，因此会触发"should have property in"的错误。

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