Как обрабатывать несовместимые изменения API с помощью Swagger, OpenAPI и генератора - PullRequest
Новая
       181

Как обрабатывать несовместимые изменения API с помощью Swagger, OpenAPI и генератора

0 голосов
/ 05 августа 2020

Мне нужно изменить 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 "из-за неправильного написания, например,

На мой взгляд, есть две возможности

  1. добавить новое поле mainIncomeNew, оставить поле mainIncomeOld и через некоторое время параллельного использования поле mainIncomeOld можно удалить -> недостатки: я должен помнить, что поле следует удалить, оно выглядит некрасиво, и кто-то может использовать старое поле, потому что оно все еще существует
  2. создайте новый файл contract_v2.yaml только с полем mainIncomeNew, используйте его как v2 и скажите api-user, что v1 скоро устареет -> это больше похоже на лучшую практику -> но у меня может быть иметь два пакета (и классов) для поддержки v1 и v2 из-за генерации кода

или есть лучший способ?

1 Ответ

0 голосов
/ 27 августа 2020

Вы правы, это варианты. Я не уверен, что кто-то еще может сказать вам, что одно из них более правильное, чем другое - я бы предпочел вариант 1 и четко отметил в описании, что старое поле устарело, но «лучший» вариант очень субъективен

...