我应该在OpenAPI中定义不同的POST和PATCH模型吗? [英] Should I define different POST and PATCH models in OpenAPI?

问题描述

我正在OpenAPI3(Swagger)中定义REST API.

I am defining a REST API in OpenAPI3 (Swagger).

我有一个具有POST的API，该POST使用的是我在组件部分中定义的模型，如下所示:

I have an API that has a POST which uses a Model I have defined in teh components section as follows:

post:
  summary: "Used to add some data"
  operationId: postMyData
  requestBody:
    content:
      application/json:
        schema:
           $ref: '#/components/schemas/MyModel'
    required: true

components:
  schemas:
    MyModel:
      type: object
      properties:
        SomeProperty1:
          type: string
        SomeProperty2:
          type: string
        SomeProperty3:
          $ref: '#/components/schemas/SomeOtherModel'
        SomeProperty4:
          type: string

现在我有一个PATCH API调用，我只想用来更新MyModel的某些数据，例如SomeProperty1和SomeProperty4.

Now I have a PATCH API call that I want to use to update only some data of MyModel, e.g. SomeProperty1 and SomeProperty4.

我应该为此PATCH操作定义一个新模型吗?像这样:

Should I define a new Model for this PATCH operation? like so:

MyPATCHModel:
  type: object
  properties:
    SomeProperty1:
     type: string
    SomeProperty4:
     type: string

然后在PATCH操作的requestBody中使用这个新的MyPATCHModel吗?这里的标准做法是什么，因为我将有几个与此类似的API.

And then use this new MyPATCHModel in the requestBody of the PATCH operation? What is the standard practice here as I will have several API that are similar to this.

推荐答案

在组合JSON模式.

例如，您可以使用PATCH方法中使用的两个属性来定义共享的MyModel模式，然后使用allOf将MyModel与仅POST属性组合在一起的另一个NewMyModel模式

In your case you could for example define a shared MyModel schema with the two properties used in the PATCH method, and then another NewMyModel schema that uses allOf to combine MyModel with the POST-only properties.

查看此问题以获取具体示例.

这篇关于我应该在OpenAPI中定义不同的POST和PATCH模型吗?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！