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

Question

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

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

Answer 1

参数描述由description在参数本身中指定。

正因为如此，参数使用schema来定义数据类型，并且模式可以有自己的description。在参数上下文中，可以将模式级别的description看作参数数据类型的描述。

这两种描述在语义上是分开的。模式级decription是缺少参数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，因为它通常是多余的。