OpenAPI - 对同一资源的每次操作不同的架构答案

【问题标题】：OpenAPI - different schema per operation on same resourceOpenAPI - 对同一资源的每次操作不同的架构
【发布时间】：2020-09-09 05:19:14
【问题描述】：

我使用 OpenAPI 3.0 来描述一个 API，其中每个资源都有一个基于其操作的微妙不同的架构。本质上，某些属性是可编辑的和/或需要的，具体取决于它是 POST 还是 PUT 请求。

除了为每个这样的操作指定架构之外，还有更好的方法吗？（其中 field2 在 PUT 上是只读的）

理想情况下，我想在一个地方指定架构（即所有属性），然后在每个操作上覆盖一些属性（例如只读）。

{
   "paths":{
      "/users":{
         "put":{
            "responses":{
               "200":{
                  "$ref":"#/components/schemas/users_put"
               }
            }
         },
         "post":{
            "responses":{
               "200":{
                  "$ref":"#/components/schemas/users_post"
               }
            }
         }
      }
   },
   "components":{
      "schemas":{
         "users_post":{
            "properties":{
               "field1":{
                  "readOnly":true,
                  "type":"integer"
               },
               "field2":{
                  "type":"string"
               }
            }
         },
         "users_put":{
            "properties":{
               "field1":{
                  "readOnly":true,
                  "type":"integer"
               },
               "field2":{
                  "type":"string",
                  "readOnly":true
               }
            }
         }
      }
   }
}

【问题讨论】：

标签： openapi

【解决方案1】：

据我所知，openapi/swagger 模型中没有 override 机制。但是组合（扩展）模型is available。

由于在您的示例中，您只需要更新 readOnly 指令（这意味着您标记了仅在响应中可用的属性）当您分别描述请求和响应时尝试其他方法。

在您的示例中，put 和 post 方法的响应将是相同的（因为它们都有 field1 和 field2），并且只有 put 会有请求（因为在 post 中所有字段都是只读的）：

（为了简洁起见，我使用 yaml，但它是 easy 转换为 json 回来）

paths:
  "/users":
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/users_put_request'
      responses:
        '200':
          "$ref": "#/components/schemas/users_response"
    post:
      responses:
        '200':
          "$ref": "#/components/schemas/users_response"
components:
  schemas:
    users_response:
      field1:
        type: integer
      field2:
        type: integer

    users_put_request:
      field2:
          type: string

可能使用这种方法可以明确地描述模型的不同部分。

【讨论】：