yaml 文件中的 in:query 和 in:header 参数

Question

我正在学习使用 spring 引导创建 rest Api。作为参考，我正在检查一些现有代码，在 yaml 文件中我发现了下面提到的两个参数

name: "name"
      in: "query"
      description: "doing something"
      x-phase-dataelem: "CONF//Y/N"
      required: false
      schema:
            type: string
            maxlength:15


name: "tame"
      in: "header"
      description: "doing something something"
      x-phase-dataelem: "CONF//Y/N"
      required: true
      schema:
            type: string
            maxlength:15

我真的无法理解这些参数

in: "query"
in: "header"
x-phase-dataelem: "CONF//Y/N"

我知道，这些是传递给客户端 url 进行处理的一些值，但无法理解这些参数。使用这 3 个参数有什么意义？

有人能帮忙吗？

Answer 1

这个 YAML 片段看起来像一个 Swagger/OpenAPI 合同。您可以在此处找到有关 OpenAPI 的更多信息并阅读其规范 - https://swagger.io/specification/

in描述了HTTP参数的位置。

引用自 OpenAPI 规范：

There are four possible parameter locations specified by the in field:

path - Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.

query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.

header - Custom headers that are expected as part of the request. Note that RFC7230 states header names are case insensitive.

cookie - Used to pass a specific cookie value to the API.

关于 x-phase-dataelem，它是您的 OpenAPI 合同中的自定义扩展。它用于提供一些关于所描述项目（包括参数）的额外metadata/information/properties。

引用自 OpenAPI 规范：

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extensions properties are implemented as patterned fields that are always prefixed by x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. Can have any valid JSON format value.

yaml 文件中的 in:query 和 in:header 参数

in:query and in:header parameters in yaml file

java

yaml