重用具有不同所需属性的模型

Question

我有一个使用复杂模型的路径，每个 http 方法具有几乎相同的属性。问题是我想为 PUT 和 POST 的请求定义 一些 必需的属性，而 GET 响应中不需要任何属性（因为服务器总是返回所有属性，并且在文档的其他地方提到） .

我创建了一个简单的 cat API 来演示我的尝试。这个想法是，对于 GET 响应，响应模型没有任何标记为 required，但 PUT 的请求必须具有 cat 的名称。

swagger: "2.0"

info:
  title: "Cat API"
  version: 1.0.0

paths:
  /cats/{id}:
    parameters:
      - name: id
        in: path
        required: true
        type: integer
    get:
      responses:
        200:
          description: Return a cat
          schema:
            $ref: "#/definitions/GetCat"
    put:
      parameters:
        - name: cat
          in: body
          required: true
          schema:
            $ref: "#/definitions/PutCat"
      responses:
        204:
          description: Cat edited

definitions:
  Cat:
    type: object
    properties:
      name:
        type: string
  GetCat:
    allOf:
      - $ref: "#/definitions/Cat"
    properties:
      id:
        type: integer
  PutCat:
    type: object
    required:
      - name
    properties:
      $ref: "#/definitions/Cat/properties"

Swagger 编辑器说这是一个有效的规范，但 name 是根据 GET 和 PUT 的要求设置的。 Swagger UI 也是如此。

我还尝试了以下版本的 PutCat：

PutCat:
  type: object
  required:
    - name
  allOf:
    - $ref: "#/definitions/Cat"

但现在一切都是可选的。

我想不通。有没有办法正确地做到这一点？

编辑：

正如Helen 正确提到的那样，我可以使用readOnly 通过GET 和PUT 来解决这个特殊情况。

但是假设我添加了必须为 PUT 提供的 breed 属性（除了 name 属性）。然后我添加 PATCH 方法，可用于更新breed 或name，而另一个保持不变，我不想根据需要设置任何一个。

Answer 1

在您的示例中，您可以对 GET 和 POST/PUT 使用单个模型，其属性仅在 GET 响应中使用，标记为 readOnly。来自spec：

readOnly

将属性声明为“只读”。这意味着它可以作为响应的一部分发送，但不能作为请求的一部分发送。标记为 readOnly 为 true 的属性不应出现在已定义模式的必需列表中。默认值为 false。

规范看起来像：

    get:
      responses:
        200:
          description: Return a cat
          schema:
            $ref: "#/definitions/Cat"
    put:
      parameters:
        - name: cat
          in: body
          required: true
          schema:
            $ref: "#/definitions/Cat"
      responses:
        204:
          description: Cat edited

definitions:
  Cat:
    properties:
      id:
        type: integer
        readOnly: true
      name:
        type: string
      breed:
        type: string
    required:
      - name
      - breed

这意味着你必须 PUT name 和 breed:

{
  "name": "Puss in Boots",
  "breed": "whatever"
}

和GET /cats/{id} 必须返回name 和breed，也可以返回id：

{
  "name": "Puss in Boots",
  "breed": "whatever",
  "id": 5
}

Answer 2

我也遇到过类似的问题。原来我的缩进是错误的。 以下语法应该有效：

PutCat:
  allOf:
    - $ref: "#/definitions/Cat"
    - type: object
      required: [name]