如何使用 swagger、openapi 和生成器处理不兼容的 api 更改答案

【问题标题】：How to handle incompatibe api changes with swagger, openapi and generator如何使用 swagger、openapi 和生成器处理不兼容的 api 更改
【发布时间】：2020-11-26 02:05:15
【问题描述】：

我必须进行非向后兼容的 API 更改，但我不确定最佳做法。目前使用 OpenApi 3 和用于代码生成的 maven 插件，配置如下。

<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>

以及下面的 Swagger 文件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

现在属性名称“mainIncomeOld”应更改为“mainIncomeNew”，因为拼写错误，例如

在我的想象中，有两种可能

添加新字段mainIncomeNew，保留字段mainIncomeOld，在并行使用一段时间后，可以删除字段mainIncomeOld -> 缺点：我必须记住该字段应该被删除，它看起来很难看，有人可能会使用旧字段，因为它仍然存在
创建一个新的contract_v2.yaml 文件，其中只有mainIncomeNew 字段，将其用作v2 并告诉api 用户v1 将很快被弃用 -> 它看起来更像是一种最佳实践 -> 但由于代码生成，我可能必须有两个包（和类）来维护 v1 和 v2

或者有没有更好的方法？

【问题讨论】：

标签： java api swagger code-generation openapi

【解决方案1】：

你是对的，这些是选项。我不确定其他人能告诉你一个比另一个更正确 - 我倾向于 option1 并在描述中明确标记旧字段已被弃用，但“最佳”选项非常主观

【讨论】：