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

问题描述

我有一条使用复杂模型的路径，每个模型的属性几乎相同.问题是我想为PUT和POST请求定义 some 必需的属性，而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响应，响应模型没有标记为必需的任何内容，但是PUT的请求必须具有猫的名称.

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编辑器说这是一个有效的规范，但是GET和PUT都需要设置name. 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.

但是假设我添加了breed属性，必须为PUT提供(除了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

将属性声明为只读".这意味着它可以作为响应的一部分发送，但绝不能作为请求的一部分发送.标记为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屋！