Come rompere il file JSON swagger 2.0 in più moduli

Question

Sto provando a suddividere il mio documento API in più file JSON che possono essere modificati indipendentemente. Tutti gli esempi che sono riuscito a trovare usano lo schema di Swagger 1.2 che ha un oggetto "api": {} per scomporlo. Sembra che manchi lo schema 2.0 (http://json.schemastore.org/swagger-2.0). Tutto ciò che definisce è un singolo array "percorsi" in cui raggruppa tutti gli endpoint API in quel singolo array. L'effetto di questo in swagger-ui è che esiste un'unica categoria "predefinita" in cui tutto viene raggruppato e non c'è modo che io possa dire di dividerlo.

TLDR: Come si fa a dividere le operazioni da percorsi nella spavalderia 2.0 schema

{ 
 
    "swagger": "2.0", 
 
    "info": { 
 
    "description": "My API", 
 
    "version": "1.0.0", 
 
    "title": "My API", 
 
    "termsOfService": "http://www.domain.com", 
 
    "contact": { 
 
     "name": "support@domain.com" 
 
    } 
 
    }, 
 
    "basePath": "/", 
 
    "schemes": [ 
 
    "http" 
 
    ], 
 
    "paths": { 
 
    "Authorization/LoginAPI": { 
 
     "post": { 
 
     "summary": "Authenticates you to the system and produces a session token that will be used for future calls", 
 
     "description": "", 
 
     "operationId": "LoginAPI", 
 
     "consumes": [ 
 
      "application/x-www-form-urlencoded" 
 
     ], 
 
     "produces": [ 
 
      "application/json" 
 
     ], 
 
     "parameters": [{ 
 
      "in": "formData", 
 
      "name": "UserName", 
 
      "description": "Login Username", 
 
      "required": true, 
 
      "type": "string" 
 

 
     }, { 
 
      "in": "formData", 
 
      "name": "Password", 
 
      "description": "Password", 
 
      "required": true, 
 
      "type": "string" 
 

 
     }], 
 
     "responses": { 
 
      "200": { 
 
      "description": "API Response with session ID if login is allowed", 
 
      "schema": { 
 
       "$ref": "#/definitions/Authorization" 
 
      } 
 
      } 
 
     } 
 
     } 
 
    } 
 
    } 
 
}

Answer 1

In realtà chiedere alcune domande in uno, e cercherò di rispondere a tutti.

In Swagger 1.2 e prima di esso, la divisione dei file era obbligatoria e artificiale. Era pensato come un modo per raggruppare le operazioni, e offre Swagger 2.0 e un metodo alternativo per farlo (ne parleremo presto).

Swagger 2.0 è infatti un singolo file, che consente di file esterni ovunque sia utilizzato $ref. Non è possibile dividere un singolo servizio in più file e combinarli come se fossero uno solo, ma è possibile specificare le operazioni per percorsi specifici esternamente (di nuovo, utilizzando la proprietà $ref).

Attualmente stiamo completando la possibilità di raggruppare diversi micro-servizi in una singola raccolta, ma alla fine, ogni micro-servizio sarà ancora un singolo file.

Come già detto, il raggruppamento di operazioni in Swagger 2.0 è cambiato e il concetto di "risorsa" non esiste più. Invece, ci sono tag (con la proprietà "tags") che possono essere assegnati per operazione. Lo tags è un array di valori e, a differenza delle versioni precedenti, ogni operazione può esistere sotto più tag se necessario. In Swagger-UI, tutte le operazioni che non hanno tag definiti finiranno sotto il tag default, che è il comportamento che hai visto. C'è una proprietà aggiuntiva tags nell'oggetto di livello superiore che consente di aggiungere descrizioni ai tag e impostare il loro ordine, ma non è obbligatorio includerlo.

Come nota finale, non ho idea di come lo schema JSON di Swagger 2.0 sia finito in http://json.schemastore.org/swagger-2.0 ma non è certamente aggiornato. Lo schema più aggiornato può essere trovato qui - http://swagger.io/v2/schema.json - ed è ancora in fase di sviluppo. Tieni presente che la fonte della verità è la specifica (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) e non lo schema, quindi in caso di conflitti, la specifica "vince".

Edit:

Abbiamo appena pubblicato una guida su riferimento. Può essere d'aiuto con alcuni casi d'uso - https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md

Answer 2

Sto cercando di capire anche questo, e ci sono alcune informazioni utili nello Swagger Google group. Sembra che il consenso sia che è possibile suddividere le definizioni in file separati fintanto che $ ref punta a un URL assoluto.Esempio qui:

https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#L32

https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json

Answer 3

Ho scritto di questo in this blog post. Puoi fondamentalmente usare la libreria JSON Refs per risolvere tutti i tuoi piccoli file Swagger in uno grande e usarlo negli strumenti.

Answer 4

Se JSON ref non ha funzionato per te, potrebbe essere utile scrivere il tuo concatenatore. Bene, invece di scrivere il tuo puoi effettivamente usare qualcosa che è già là fuori. Qualsiasi motore di template funzionerà. Nel mio caso, Handlebars si è rivelata molto utile (poiché Handlebars mantiene effettivamente il rientro, che è perfetto per i file Yaml poiché sono sensibili al maiuscolo/minuscolo).

allora si può avere uno script di build in Node:

'use strict'; 

var hbs = require('handlebars'); 
var fs = require('fs'); 

var dir = __dirname + '/your_api_dir'; 

var files = fs.readdirSync(dir); 

files.forEach((fileName) => { 
    var raw = fs.readFileSync(dir + '/' + fileName, 'utf8'); 
    hbs.registerPartial(file, raw); 
}); 

var index = fs.readFileSync(dir + '/index.yaml'); 

var out = hbs.compile(index.toString()); 

Leggi tutto quanto riguarda la questione on my blog.

Answer 5

Nota che RepreZen API Studio ora supporta i progetti multi-file Swagger/Open API tramite la sintassi $ref discussa qui. Quindi puoi suddividere i grandi progetti Swagger in moduli per abilitare il riutilizzo e la collaborazione di gruppo. È quindi possibile utilizzare il normalizzatore Swagger incorporato per creare un singolo file Swagger consolidato quando è necessario portare il modello dell'API all'esterno dell'ambiente di progettazione/sviluppo.

Nota: nell'interesse della completa divulgazione, sono Product Manager di RepreZen. Mi sono imbattuto in questa discussione la settimana scorsa e ho pensato di chip.

Answer 6

Se JSON non funziona per voi bis, è anche possibile e si utilizza node.js, è anche possibile utilizzare module.exports

ho il mio definizioni nei moduli e posso richiedere un modulo all'interno di un modulo:

const params = require(./parameters); 
module.exports = { 
    description: 'Articles', 
    find: { 
    description: 'Some description of the method', 
    summary: 'Some summary', 
    parameters: [ 
     params.id, 
     params.limit, 


...