How to define global parameters in OpenAPI?

Question

I\'m preparing my API documentation by doing it per hand and not auto generated. There I have headers that should be sent to all APIs and don\'t know if it is possible to de

Answer 1

It depends on what kind of parameters they are.

The examples below are in YAML (for readability), but you can use http://www.json2yaml.com to convert them to JSON.

Security-related parameters: Authorization header, API keys, etc.

Parameters used for authentication and authorization, such as the Authorization header, API key, pair of API keys, etc. should be defined as security schemes rather than parameters.

In your example, the X-ACCOUNT looks like an API key, so you can use:

swagger: "2.0"
...

securityDefinitions:
  accountId:
    type: apiKey
    in: header
    name: X-ACCOUNT
    description: All requests must include the `X-ACCOUNT` header containing your account ID.

# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
  - accountId: []

or in OpenAPI 3.0:

openapi: 3.0.0
...

components:
  securitySchemes:
    accountId:
      type: apiKey
      in: header
      name: X-ACCOUNT
      description: All requests must include the `X-ACCOUNT` header containing your account ID.

# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
  - accountId: []

Tools may handle security schemes parameters differently than generic parameters. For example, Swagger UI won't list API keys among operation parameters; instead, it will display the "Authorize" button where your users can enter their API key.

Generic parameters: offset, limit, resource IDs, etc.

OpenAPI 2.0 and 3.0 do not have a concept of global parameters. There are existing feature requests:
Allow for responses and parameters shared across all endpoints
Group multiple parameter definitions for better maintainability

The most you can do is define these parameters in the global parameters section (in OpenAPI 2.0) or the components/parameters section (in OpenAPI 3.0) and then $ref all parameters explicitly in each operation. The drawback is that you need to duplicate the $refs in each operation.

swagger: "2.0"
...

paths:
  /users:
    get:
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      ...
  /organizations:
    get:
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      ...

parameters:
  offset:
    in: query
    name: offset
    type: integer
    minimum: 0
  limit:
    in: query
    name: limit
    type: integer
    minimum: 1
    maximum: 50

To reduce code duplication somewhat, parameters that apply to all operations on a path can be defined on the path level rather than inside operations.

paths:
  /foo:
    # These parameters apply to both GET and POST
    parameters:
      - $ref: '#/parameters/some_param'
      - $ref: '#/parameters/another_param'

    get:
      ...
    post:
      ...