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

Question

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

我创建了一个简单的cat API来演示我尝试过的东西.我们的想法是,对于GET响应,响应模型没有标记为必需的任何内容,但PUT的请求必须具有猫的名称.

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正确提到的,我可以用readOnlyGET和PUT来解决这个特殊情况.

但是,假设我添加了breed必须name为PUT 提供的属性(除了属性).然后我添加了PATCH方法,可以用来更新其中一个breed或name另一个保持不变,我想根据需要设置它们.

Answer 1

在您的示例中,您可以将单个模型用于GET和POST/PUT,其中的属性仅在标记为的GET响应中使用readOnly.从规格:

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

这意味着你必须把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]