如何表示无关的 Swagger 参数



我们的业务正在寻求创建一个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 文档的主要目的是生成少量客户端应用程序(我们控制的所有应用程序(以与服务器进行交互。

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

对于此类参数,是否有推荐的方法?

OpenAPI 定义充当 API 提供者和客户端之间的协定。除其他功能外,它还可用于生成客户端 SDK。因此,OpenAPI 定义应该精确地描述您的 API,包括请求正文格式、所需参数、身份验证等。

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

为了减少代码重复,您可以在全局parameters部分(对于 OpenAPI 2.0(或components/parameters部分(对于 OpenAPI 3.0(中定义可重用参数,然后从各个路径或操作中$ref它们,如下所示:
Swagger/OpenAPI - 使用 $ref 传递可重用的定义参数

请注意,目前无法$ref一组参数。在此处跟踪相应的功能请求:
分组多个参数定义以提高可维护性
全局/公共参数(由于某种原因,即使它没有实现,也已关闭(

最新更新