How to handle incompatibe api changes with swagger, openapi and generator

Question

I have to do a non-backwards compatible API change and I'm not sure about the best practice. Currently OpenApi 3 is used and the maven plugin for code generation with the following config.

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>4.3.1</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${basedir}/../spec/src/main/resources/contract_v1.yaml</inputSpec>
        <generatorName>java</generatorName>
        <generateSupportingFiles>true</generateSupportingFiles>
        <apiPackage>de.company.client</apiPackage>
        <modelPackage>de.company.dto</modelPackage>
        <generateApis>false</generateApis>
        <generateApiTests>false</generateApiTests>
        <generateModelTests>false</generateModelTests>
        <configOptions>
          <library>resttemplate</library>
          <sourceFolder>src/main/java</sourceFolder>
          <useTags>true</useTags>
          <useBeanValidation>true</useBeanValidation>
          <dateLibrary>java8-localdatetime</dateLibrary>
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>

and the following Swagger file contract_v1.yaml

openapi: 3.0.0
info:
  version: 1.0
  title: "testapi"

paths:
  /v1/contracts/:
    post:
      operationId: contracts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contract'

      responses:
        "200":
          description: success

        "404":
          description: error

components:
  schemas:

    Contract:
      type: object
      properties:
        debtorOne:
          $ref: '#/components/schemas/Debtor'

    Debtor:
      type: object
      properties:
        mainIncomeOld:
          type: number
          format: float
          example: 4500.00

Now the name of the property "mainIncomeOld" should be changed to "mainIncomeNew", due to a miss spelling eg

In my imgagination there are two possibilites

1. add the new field mainIncomeNew , keep the field mainIncomeOld and after a while of parallel use the field mainIncomeOld can be removed -> disandvantages: I have to remember that the field should be removed, it looks ugly and somebody may use the old field because it still exists
2. create a new contract_v2.yaml file with only the field mainIncomeNew , use this as v2 and tell the api-user that v1 will be deprecated soon -> it looks for me more like a best practice -> but I may have to have two packages (and classes) to maintain v1 and v2 due to codegeneration

or is there a better way?

Answer 1

You are correct, those are the options. I am not sure anyone else can tell you one is more right than the other - I would tend towards option1 and clearly mark in the description that the old field is deprecated, but the "best" option is very subjective