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 define parameters globally for the whole API or not?

Some of these headers are static and some has to be set when call to API is made, but they are all the same in all APIs, I don't want to copy and paste parameters for each API and each method as this will not be maintainable in the future.

I saw the static headers by API definition but there is no single document for how somebody can set them or use them.

Is this possible at all or not?

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:
      ...

Answer 2

If you're talking about header parameters sent by consumer when calling the API...

You can at least define them once and for all in parameters sections then only reference them when needed. In the example below:

• CommonPathParameterHeader, ReusableParameterHeader and AnotherReusableParameterHeader are defined once and for all in parameterson the root of the document and can be used in any parameters list
• CommonPathParameterHeaderis referenced in parameters section of /resources and /other-resources paths, meaning that ALL operation of these paths need this header
• ReusableParameterHeader is referenced in get /resources meaning that it's needed on this operation
• Same thing for AnotherReusableParameterHeader in get /other-resources

Example:

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
    post:
      responses:
        '204':
          description: Succesfully created.

If you're talking about header sent with each API response...

Unfortunately you cannot define reusable response headers. But at least you can define a reusable response containing these headers for common HTTP responses such as a 500 error.

Example:

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
    post:
      responses:
        '204':
          description: Succesfully created.
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
        '500':
          $ref: '#/responses/Standard500ErrorResponse'

responses:
  Standard500ErrorResponse:
    description: An unexpected error occured.
    headers:
      X-Rate-Limit-Remaining:
        type: integer
      X-Rate-Limit-Reset:
        type: string
        format: date-time

About OpenAPI (fka. Swagger) Next version

The OpenAPI spec (fka. Swagger) will evolve and include the definition of reusable response headers among other things (cf. https://github.com/OAI/OpenAPI-Specification/issues/563).

Answer 3

As per this Swagger issue comment, support for global parameters (including header parameters) is not planned in foreseeable future, but to limit the repetition you should use parameters references as in @Arnaud's answer (parameters: - $ref: '#/parameters/paramX').