Skip to content

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. parameters written on the path item, next to get and post, 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.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish