Should I define different POST and PATCH models in OpenAPI?

Question

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

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

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

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

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

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.

Colon

Answer 1

Check the docs on combining JSON schemas.

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.

Check this question for a concrete example.

Khano