31

我有一条使用复杂模型的路径，每个 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 Editor 说这是一个有效的规范，但是name根据 GET 和 PUT 的要求进行设置。Swagger UI 也是如此。

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

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

但现在一切都是可选的。

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

编辑：

正如Helen正确提到的，我可以使用readOnlyGET 和 PUT 来解决这个特殊情况。

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

4

2 回答 2

32

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

readOnly

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

规范看起来像：

    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

这意味着您必须 PUTname和breed：

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

andGET /cats/{id}必须返回nameandbreed并且还可能返回id:

{
  "name": "Puss in Boots",
  "breed": "whatever",
  "id": 5
}
于 2016-11-28T12:01:33.273 回答
7

我有一个类似的问题。原来我的缩进是错误的。以下语法应该有效：

PutCat:
  allOf:
    - $ref: "#/definitions/Cat"
    - type: object
      required: [name]
于 2018-03-21T15:15:12.837 回答