跳到主要内容

Operation 对象

描述对路径的某个操作。

固定字段​

字段名类型描述
tags[string]用于控制 API
文档的标签列表，标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件。
summarystring
对此操作行为的简短描述。
descriptionstring
对此操作行为的详细解释。CommonMark syntax可以被用来呈现富文本格式.
externalDocsExternal Documentation 对象
附加的外部文档。
operationIdstring用于标识此操作的唯一字符串，这个

id 在此 API 内包含的所有操作中必须是唯一的。相关的工具和库可能会使用此 operationId 来唯一的标识一个操作，因此推荐在命名时符合一般的编程命名习惯。 | | parameters | [Parameter 对象 | Reference 对象] | 定义可用于此操作的参数列表，如果一个同名的参数已经存在于 Path Item ，那么这里的定义会覆盖它但是不能移除上面的定义。这个列表不允许包含重复的参数，参数的唯一性由 name 和 location 的组合来确定。这个列表可以使用 Reference 对象 来连接定义于 OpenAPI 对象 components/parameters 的参数。 | | requestBody | Request Body 对象 | Reference 对象 | 可用于此操作的请求体。requestBody 只能被用于 HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法，在其他没有明确定义的请求方法中，requestBody的消费者应该应该忽略requestBody。 | | responses | Responses 对象 | 必选. 定义执行此操作后的可能的响应值列表。 | | callbacks | Map[string, Callback 对象 | Reference 对象] | 一组相对于父操作的可能出现的回调映射，A map of possible out-of band callbacks related to the parent operation. 映射中的每一个键都唯一的映射一个 Callback 对象， that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. | | deprecated | boolean | 声明此操作已经被废弃，使用者应该尽量避免使用此操作，默认的值是 false。 | | security | [Security Requirement 对象] | 声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象，但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明，因此可以声明一个空数组来变相的移除顶层的安全声明。 | | servers | [Server 对象] | 一个可用于此操作的额外的 server 数组，这里的定义会覆盖 Path Item 对象 或 顶层的定义。 |

这个对象可能会被规范扩展扩展。

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": "Invalid input",
      "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:
        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: Invalid input
    content:
      'application/json': { }
      'application/xml': { }
security:
  - petstore_auth:
      - write:pets
      - read:pets