重用具有不同所需属性的模型 [英] Re-using model with different required properties

问题描述

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

I have a path that uses complex models with almost identical properties for each http method. The problem is that I want to define some required properties for the request of PUT and POST, while no properties are required in GET response (as the server always returns all properties and it's mentioned elsewhere in the documentation).

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

I created a simple cat API to demonstrate what I've tried. The idea is that for GET response the response model doesn't have anything marked as required, but the request of PUT must have a name for the 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 也是如此.

Swagger Editor says that this is a valid specification, but name is set as required for both GET and PUT. The same goes with Swagger UI.

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

I also tried the following version of PutCat:

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

但现在一切都是可选的.

But now everything is optional.

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

I can't figure this out. Is there a way to do this properly?

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

As Helen correctly mentioned, I can use readOnly to solve this particular case with GET and PUT.

但假设我添加了必须为 PUT 提供的 breed 属性(除了 name 属性之外).然后我添加 PATCH 方法，该方法可用于更新 breed 或 name 而另一个保持不变，我不想根据需要设置这两个.

But let's say I add breed property which must be provided (in addition to the name property) for PUT. Then I add PATCH method, which can be used to update either breed or name while the other remains unchanged, and I want to set neither of those as required.

推荐答案

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

In your example, you can use a single model for both GET and POST/PUT, with properties only used in the GET response marked as readOnly. From the spec:

只读

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

Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is 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:

This means you must PUT the name and breed:

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

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

and GET /cats/{id} must return the name and breed and may also return the id:

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

这篇关于重用具有不同所需属性的模型的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！