描述路径上的单个 API 操作。

4.8.10.1 固定字段

字段名称	类型	描述
标签	[string]	用于 API 文档控制的一组标签。标签可用于根据资源或任何其他限定符对操作进行逻辑分组。
摘要	字符串	操作作用的简短摘要。
描述	字符串	操作行为的详细说明。[CommonMark 规范] 语法可以用于富文本表示。
外部链接	外部文档对象	此操作的其他外部链接文档。
操作 ID	字符串	用于标识操作的唯一字符串。ID必须在 API 中描述的所有操作中唯一。operationId 值区分大小写。工具和库可以使用 operationId 唯一标识操作，因此，建议遵循常见的编程命名约定。
参数	参数对象  引用对象	适用于此操作的参数列表。如果参数已在路径项中定义，则新定义将覆盖它，但永远不会删除它。列表不得包含重复的参数。唯一参数由名称和位置的组合定义。该列表可以使用引用对象链接到在OpenAPI 对象的 components/parameters中定义的参数。
请求体	请求体对象  引用对象	适用于此操作的请求体。requestBody 在 HTTP 1.1 规范 [RFC7231] 第 4.3.1 节 已明确定义请求体的语义的 HTTP 方法中得到完全支持。在 HTTP 规范含糊不清的其他情况下（例如 GET、HEAD 和 DELETE），requestBody 是允许的，但没有明确定义的语义，并且如果可能，应该避免。
响应	响应对象	执行此操作后返回的可能响应列表。
回调	Map[string, 回调对象  引用对象]	与父操作相关的可能带外回调的映射。键是回调对象的唯一标识符。映射中的每个值都是一个回调对象，它描述了 API 提供者可能发起的请求以及预期的响应。
已弃用	布尔值	声明此操作已弃用。使用者应该避免使用声明的操作。默认值为 false。
安全	[安全需求对象]	声明此操作可以使用哪些安全机制。值列表包含可使用的替代安全需求对象。只需要满足其中一个安全需求对象即可授权请求。若要使安全成为可选，可以在数组中包含一个空的安全需求 ({})。此定义会覆盖任何已声明的顶级 security。若要移除顶级安全声明，可以使用空数组。
服务器	[服务器对象]	此操作的服务替代 server 数组。如果在路径项对象或根级别指定了替代 server 对象，则此值将覆盖它。

此对象*可以使用 规范扩展 进行扩展。

4.8.10.2 Operation 对象示例

{
  "tags": [
    "pet"
  ],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "description": "Updated name of the pet",
              "type": "string"
            },
            "status": {
              "description": "Updated status of the pet",
              "type": "string"
            }
          },
          "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       type: object
       properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content:
      'application/json': {}
      'application/xml': {}
  '405':
    description: Method Not Allowed
    content:
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets