How to represent extraneous Swagger parameters

Question

Our business is looking to create a Swagger document to represent an internal server.

For various reasons, each request is required to include a series of extraneous header parameters:

parameters:
    - name: device_id
      in: header
      required: false
      type: string
    - name: ip_address
      in: header
      required: true
      type: string
    - name: client_id
      in: header
      required: true
      type: string
    - name: request_id
      in: header
      required: true
      type: string

The server will reject the request if the parameters are not included but the parameters themselves are unrelated to the request being made.

The primary purpose of the Swagger document is to generate a small number of client applications (all of which we control) to interact with the server.

We could add each parameter explicitly on every request but this would result in repetition within the document and additional handling within the clients. Alternatively, we could regard these parameters as metadata and exclude them from the document, relying on the clients to add them to each request appropriately.

Is there a recommended approach for such parameters?

score 0 · Accepted Answer · answered Apr 30 '18 at 10:59

An OpenAPI definition serves as a contract between the API provider and the clients. It can be used, among other things, to generate client SDKs. So it's expected that an OpenAPI definition describes your API precisely, including the request body format, required parameters, authentication, etc.

All required parameters should be defined explicitly.

To reduce the code duplication, you can define reusable parameters in the global parameters section (for OpenAPI 2.0) or components/parameters section (for OpenAPI 3.0), and then $ref them from individual paths or operations, as shown here:
Swagger/OpenAPI - use $ref to pass a reusable defined parameter

Note that there's currently no way to $ref a group of parameters. The corresponding feature requests are tracked here:
Group multiple parameter definitions for better maintainability
Global/common parameters (this one is closed for some reason, even though it's not implemented)

How to represent extraneous Swagger parameters

1 Answers1