Definire una proprietà con un tipo di dati misto in Swagger

Question

Ho già un documento di swagger funzionante che genera documentazione utilizzando il progetto Swagger-UI, ma sto riscontrando un problema minore.

Mongoose supporta un tipo di dati Mixed, che è fondamentalmente un oggetto non strutturato che può contenere qualsiasi cosa. Tuttavia, in base alle specifiche Swagger, gli unici valori possibili per type di proprietà sono string, integer, number, boolean e array. Non sono riuscito a trovare nulla nella documentazione, su Google o nei problemi aperti per il progetto Swagger-Spec su GitHub che consentirebbe tipi di dati misti.

Nella documentazione di Swagger-Spec, dove definiscono le opzioni type, fanno riferimento al progetto JSON-Schema. Secondo la specifica JSON-Schema, l'opzione object dovrebbe essere un'opzione, ma non è elencata come valore potenziale nella specifica Swagger.

Qualcuno sa di un modo per indicare in un documento Swagger che la proprietà di un modello può contenere qualsiasi valore (un singolo valore primitivo o un oggetto)?

Esempi

definizione di schema Mongoose:

var sampleSchema = new mongoose.Schema({ 
    lookupCodes : { type: [mongoose.Schema.Types.Mixed] }, 
    address: { type: mongoose.Schema.Types.Mixed } 
}); 

mongoose.model('Sample', sampleSchema); 

utilizzo del modello mongoose:

var Sample = mongoose.model('Sample'); 
var doc = new Sample(); 

Questi sono tutti valori validi per le due proprietà definite:

doc.lookupCodes = ['A', 'B', 3, 4, 5, 'F']; 

doc.lookupCodes = ['A', { code: '123' }, 5]; 

doc.address = '123 Main St., San Jose, CA, 95125'; 

doc.address = { street: '123 Main St.', city: 'San Jose', state: 'CA', postalCode: '95125'} 

Swagger 1.2 documento (frammento):

"models": { 
    "Sample": { 
     "properties": { 
      "lookupCodes": { 
       "type": "array", 
       "items": { 
        "type": "??????" 
       }, 
       "description": "An array of lookup codes. Codes can be strings, numbers or an object containing the `code` property." 
      }, 
      "address": { 
       "type": "??????", 
       "description": "An address. This value can be a single string, containing all the elements of the address together, or it can be a structured object with each of the elements as separate properties of the object." 
      }, 

Sto semplicemente cercando un modo per lasciare che lo sviluppatore la visualizzazione della documentazione di sapere che una proprietà specifica all'interno di un modello potrebbe accettare/restituire qualsiasi valore (variabile primitiva o un oggetto).

Answer 1

Nella domanda si descrivono due casi d'uso distinti.

Il primo è l'utilizzo di un array con valori misti, mentre il secondo è un campo specifico che può avere qualsiasi valore (sia esso un oggetto, primitivo e potenzialmente un array).

Swagger esplicitamente non supporta tale modellazione. Ci sono diverse ragioni per farlo, ma si concentrano sul determinismo e sul supporto linguistico. Mentre i linguaggi dinamici possono supportare più facilmente le API non deterministiche e le lingue con caratteri dattili possono supportare facilmente i tipi dinamici, le altre lingue ne risentirebbero. Le API sono pensate per l'interoperabilità, essendo indipendenti dalla lingua, quindi devi considerare queste restrizioni.

Mentre Swagger è inteso come strumento di documentazione, il suo ecosistema di strumenti include soluzioni che dovrebbero essere in grado di produrre e consumare tali API praticamente in qualsiasi lingua. Ovviamente, non può avere una copertura del 100%, ma cerca di evitare problemi noti.

Swagger 2.0 aggiunge molta più flessibilità in termini di definizione dei modelli, consentendo anche a oggetti di forma libera (e di fare note - oggetti, non primitive).Sebbene sia altamente sconsigliato l'uso in generale, ci sono casi d'uso in cui non può essere evitato, ma anche le lingue fortemente tipizzate possono occuparsene (posso elaborare i casi d'uso, ma non è pertinente alla domanda a mano).

Come informazioni aggiunte: pensate dal punto di vista della documentazione e userò il vostro campo address come esempio. Quello che stai dicendo qui, API Wise, è che il campo indirizzo è un jolly. Puoi accettare qualsiasi cosa, e non deve essere un indirizzo, non deve avere una struttura, non deve avere informazioni specifiche. Se qualcuno vuole, può usare quel campo per memorizzare un codice di lancio nucleare. Ora, se questa è la tua intenzione, contrassegna semplicemente il campo come valore di stringa, e se qualcuno vuole inviare un oggetto JSON serializzato come una stringa, si adatterà altrettanto bene.