如何表示无关的 Swagger 参数

Question

我们的业务正在寻求创建一个 Swagger 文档来表示内部服务器。

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

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 提供商与客户之间的合同。除其他外，它还可以用于 generate client SDKs。所以希望 OpenAPI 定义能够准确描述你的 API，包括请求体格式、所需参数、身份验证等

应明确定义所有必需的参数。

为了减少代码重复，您可以在全局 parameters 部分（对于 OpenAPI 2.0）或 components/parameters 部分（对于 OpenAPI 3.0)，然后 $ref 来自各个路径或操作的它们，如下所示：
Swagger/OpenAPI - use $ref to pass a reusable defined parameter

请注意，目前无法 $ref 一组参数。此处跟踪相应的功能请求：
Group multiple parameter definitions for better maintainability
Global/common parameters（由于某种原因这个已经关闭了，尽管它没有实现）

如何表示无关的 Swagger 参数

How to represent extraneous Swagger parameters

swagger

openapi