Question

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

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

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参数

1 个答案: