allOf and parameters in OpenAPI: what works and what to write instead
Last checked and updated
allOf is a schema keyword: it combines schemas. It can be used inside a parameter's schema. It cannot merge parameters themselves: the parameters of an operation must be a list, each entry one parameter or a $ref to one. To reuse a set of parameters, define each under components/parameters and reference them one by one.
What does not work
paths:
/orders:
get:
parameters:
allOf:
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
A linter refuses the document:
$ apigit lint bad31.yaml
18:18 error oas3-schema "parameters" property must be array. (paths./orders.get.parameters)
What to write instead
paths:
/orders:
get:
parameters:
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
components:
parameters:
Limit:
name: limit
in: query
description: Page size
schema:
type: integer
minimum: 1
maximum: 100
Offset:
name: offset
in: query
description: Items to skip
schema:
type: integer
minimum: 0
There is no way to reference "the paging parameters" with one $ref: each reference stands for exactly one parameter. Two things reduce the repetition:
- Path-level parameters.
parameterswritten on the path item, next togetandpost, apply to every operation of that path. - One object parameter. A single query parameter whose schema is an object (
style: form,explode: true) spreads its properties into separate query parameters, and that schema can be a$ref. Tools support this less evenly than plain parameters: test it with the generators and the documentation you use.
Where allOf is valid: inside the schema
- name: filter
in: query
description: Filter combining two schemas
schema:
allOf:
- type: string
- minLength: 3
The value must satisfy both parts. A mock server generated from the file enforces it:
$ curl -i 'http://127.0.0.1:4641/orders?filter=ab'
HTTP/1.1 422 Unprocessable Entity
{"errors":[{"in":"query","name":"filter","message":"must NOT have fewer than 3 characters"}],
"type":"https://apigit.com/mock/problems/invalid-request",
"title":"The request does not match the API description","status":422, ...}
The referenced parameters are enforced the same way, limit=500 against maximum: 100:
{"errors":[{"in":"query","name":"limit","message":"must be <= 100"}], ...}
The usual reason for allOf in a parameter is to add a constraint or a description to a shared schema: allOf: [{ $ref: "#/components/schemas/Id" }, { description: "The order's id" }]. In OpenAPI 3.1 a description can also sit next to the $ref.