如何表示无关的Swagger参数

Question

我们的业务希望创建一个大摇大摆的文档来表示内部服务器。

由于各种原因，每个请求都需要包括一系列无关的头参数：

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

如果不包括参数，但参数本身与正在发出的请求无关，服务器将拒绝该请求。

Swagger文档的主要目的是生成少量客户机应用程序（我们控制所有这些应用程序）来与服务器交互。

我们可以在每个请求上显式地添加每个参数，但这将导致文档中的重复和客户端中的额外处理。或者，我们可以将这些参数视为元数据，并将它们从文档中排除，依赖于客户机将它们适当地添加到每个请求中。

对于这些参数是否有推荐的方法？

Answer 1

OpenAPI定义充当API提供者和客户机之间的契约。除其他外，它可用于生成客户端SDK。因此，希望OpenAPI定义能够准确地描述API，包括请求正文格式、所需参数、身份验证等。

所有必需的参数都应该显式定义。

为了减少代码重复，您可以在全局parameters部分（对于OpenAPI 2.0)或components/parameters部分（对于OpenAPI 3.0)中定义可重用参数，然后在各个路径或操作中定义$ref参数，如下所示:
swagger/openapi-use$ref传递可重用定义的参数

请注意，目前没有办法$ref一组参数。在这里跟踪相应的特性html" target="_blank">请求:
为更好的可维护性对多个参数定义进行分组
全局/公共参数（由于某种原因关闭了这个参数，尽管它没有实现）