Versioning semantico in OpenAPI con stringa "enum": nuovi valori OK?

Question

Versioning semantico in OpenAPI con stringa "enum": nuovi valori OK?

#1 da (8 voti)
#2 da (5 voti)

3

Il mio team si sta preparando ad aggiungere nuove funzionalità a un contratto OpenAPI e alla nostra implementazione di esso. Ci sono clienti preesistenti. Stiamo pianificando di utilizzare la nostra API dalla v1.1 alla v1.2 rispettando nel pieno il versioning semantico .

Il nostro team sta discutendo se dobbiamo andare alla v2.0 invece della v1.2 se aggiungiamo nuovi possibili valori a una definizione di tipo come questa (in yaml):

Thing:
  type: object
  properties:
    field:
      type: string
      enum:
        - PreExistingValue1
        - PreExistingValue2
        - NewValue1
        - NewValue2

Con NewValue1 e NewValue2 che sono state introdotte di recente nella v1.2. L'API v1.1 non ha questi due valori nell'enumerazione.

EDIT : il nostro Thing viene utilizzato solo nei dati risposta .

Fondamentalmente la mia domanda è, è OK farlo con un aumento della versione minore , oppure dobbiamo aumentare il numero di versione maggiore per cambiare l'API in questo modo ?

Cercherò di non rivelare quale lato di questo argomento sono attivo e rappresentare gli argomenti for / against il più neutro possibile:

Sostenendo solo un aumento di versione minore, un membro del team ha dichiarato che, in definitiva, questo campo è una stringa e che non sta cambiando, quindi è OK per questa stringa assumere nuovi valori e che non è una minaccia per retrocompatibilità. È ragionevole aspettarsi che un client ignori un valore di stringa che non capisce in questo campo.
Sostenendo solo un aumento di versione minore, un membro del team ha dichiarato che l'enum OpenAPI è "solo documentazione", che fondamentalmente stiamo solo dichiarando un campo stringa nel contratto, nient'altro.
Discutendo per un aumento della versione principale, un membro del team ha dichiarato che poiché il contratto lo definisce come enum, il contratto in effetti garantisce che la stringa avrà solo determinati valori; e con questo cambiamento la garanzia è ora infranta. A seconda della scelta del framework di serializzazione nell'implementazione del client, i dati che utilizzano i nuovi valori possono essere effettivamente rifiutati automaticamente all'interno del codice framework.

Per me, questa differenza di opinioni all'interno della squadra sembra ridursi alla domanda su quanto "strong" sia il concetto di enum in OpenAPI - se deve essere considerato come parte della definizione del tipo o, come l'unica squadra membro ha detto, "solo documentazione".

All'interno della specifica, enum si riferisce a questo IETF specifica in cui si trovano le istanze di enum:

An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.

Ma le specifiche non dicono "se e solo se". Dice solo "se".

enum semantic-versioning openapi

posta wberry 07.04.2017 - 18:56

fonte

2 risposte

5

Alla fine della giornata, le regole e i regolamenti sono lì per far rispettare un'idea, ovvero che qualsiasi cambiamento che possa causare la rottura dei clienti è accompagnato da una modifica sostanziale della versione. Questo è il nucleo principale del versioning semantico e seguirlo nello spirito è più importante che seguire la lettera delle regole.

Quindi la modifica dell'insieme di valori nel tuo tipo enumerato interrompe qualcosa? Il fatto che i valori siano serializzati come stringhe è irrilevante. Semanticamente, quelle stringhe rappresentano una scelta da un set limitato.

L'aggiunta di una nuova scelta in un tipo di documento accettato dalla tua API non ha chiaramente intenzione di rompere nulla. Nessun client genererà il nuovo valore, ma (presumibilmente) nulla li richiede,

Se la tua API può generare il valore in una risposta che invia, tuttavia, le cose sono diverse. I clienti esistenti possono vedere valori che non sanno come gestire e che probabilmente falliranno. In questo caso, è previsto un aumento della versione principale.

Un caso borderline è se il tipo è usato nelle risposte, ma un client non può vedere il nuovo valore a meno che non usi nuove funzionalità. Questo potrebbe essere sostenuto in entrambi i modi.

risposta data 07.04.2017 - 19:28

fonte

Leggi altre domande sui tag enum semantic-versioning openapi

Ho sbagliato a non essere d'accordo con A Gentle Introduzione alle best practice sui modelli di symfony? [chiuso] La spaziatura è effettivamente equivalente al lungo odore del codice metodo?

score 8 · Accepted Answer

Sono a conoscenza del fatto che devi incrementare il numero della versione principale se il tuo codice introduce modifiche irrisolte.

Se Thing viene utilizzato esclusivamente per l'input e ora stai accettando un paio di nuovi valori, allora non infrangerete alcun codice esistente.

Tuttavia, se stai restituendo Thing e ho un codice come

switch (myThing) {
    case PreExistingValue1:
        doProcess1(myThing);
        break;
    case PreExistingValue2:
        doSomethingElse();
        break;
    default:
        throw new NotImplementedException();
}

restituire nuovi valori interromperà il mio codice. È qualcosa che mi piacerebbe sapere.