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

Question

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

我创建了一个简单的猫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" 

扬鞭编辑说，这是一个有效的规范，但name作为要求都设置GET和PUT。 Swagger UI也一样。

我也试过PutCat以下版本：

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

但现在一切是可选的。

我无法弄清楚这一点。有没有办法正确地做到这一点？

编辑：

由于Helen正确提到的，我可以用readOnly解决与GET和PUT这种特殊情况下。

但是让我们说，我添加breed财产必须提供（除了name属性）为PUT。然后我添加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 

这意味着你必须把name和breed：

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

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

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