How to define global parameters in OpenAPI?

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?

Solution

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