OpenAPI 参数描述与参数模式描述

Question

在 OpenAPI 3.0 中，我想知道 describing parameters 时有什么区别。例如，下面的描述“Foo”和“Bar”有什么区别？如果有意义的话，“Foo”的一个更多用于参数的语义，而“Bar”的一个更多用于语法吗？一般应该只使用一个（如果是的话，应该使用哪个）？

{
  "name": "someParameter",
  "in": "query",
  "description": "Foo",
  "schema": {
    "type": "string",
    "description": "Bar"
  }
}

Answer 1

参数说明由参数本身的description指定。

碰巧参数使用 schema 来定义数据类型，模式可以有自己的 description。在参数的上下文中，您可以将架构级别 description 视为参数的 数据类型 .

的描述

这两个描述在语义上是分开的。架构级别 decription 是 NOT a fallback，因为缺少参数 description。

这是另一个例子：

paths:
  /users/{id}:
    delete:
      summary: Delete a user
      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the user you want to delete.
          schema:
            type: string
            format: uuid
            description: >-
              A unique identifier in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".

实际上，参数通常没有指定架构级别 description，因为它通常是多余的。

OpenAPI 参数描述与参数模式描述

OpenAPI parameter description vs parameter schema description

openapi