OpenAPI 规范中的路由

在 OpenAPI 规范中，我们可以定义 API 的路由信息，使得我们能够清晰地了解 API 的结构和使用方法。然而，很多开发者可能会面临这样的问题：OpenAPI 规范中虽然定义了路由，但是没有定义 onPUT 操作。

PUT 请求的作用

在 RESTful API 中，PUT 请求通常用于更新资源。它表示客户端想要用新的数据替换掉服务端的某个资源。

在 OpenAPI 规范中，PUT 是可以被定义的，但是确实没有定义 onPUT 操作。那么怎么办呢？

如何定义 onPUT 操作

虽然 OpenAPI 规范中没有定义 onPUT，但是我们可以使用 x- 前缀来定义自己的扩展字段。比如我们可以在 parameters 中定义我们自己的 x-onPUT，并说明它的作用。

paths:
  /users/{id}:
    put:
      summary: Update a user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the user to update
          schema:
            type: integer
        - name: user
          in: body
          description: Updated user object
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: OK
    x-onPUT:
      description: Update a user by ID

在上面的示例中，我们在 /users/{id} 的 put 操作下添加了一个 x-onPUT 字段，说明其作用是更新用户信息。

总结

在 OpenAPI 规范中，虽然没有定义 onPUT 操作，但是我们可以使用 x- 前缀自定义扩展字段，来说明 PUT 请求的作用。这样我们就能够更好地理解我们的 API 结构，为后续的开发和维护提供了帮助。