webentwicklung-frage-antwort-db.com.de

Wie man eine swagger 2.0 JSON-Datei in mehrere Module aufteilt

Ich versuche, mein API-Dokument in mehrere JSON-Dateien aufzuteilen, die unabhängig voneinander bearbeitet werden können. Alle Beispiele, die ich gefunden habe, verwenden das Swagger 1.2-Schema, das ein "api": {} -Objekt zum Zerlegen enthält. Das scheint im 2.0-Schema zu fehlen ( http://json.schemastore.org/swagger-2. ). Alles, was definiert wird, ist ein einzelnes "Pfade" -Array, in dem alle API-Endpunkte in diesem einzelnen Array gebündelt werden. Der Effekt davon in der Swagger-UI ist, dass es eine einzige "Standard" -Kategorie gibt, in der alles gebündelt wird, und keine Möglichkeit, es aufzuteilen.

TLDR: Wie werden Operationen von Pfaden im swagger 2.0-Schema getrennt?

{
  "swagger": "2.0",
  "info": {
    "description": "My API",
    "version": "1.0.0",
    "title": "My API",
    "termsOfService": "http://www.domain.com",
    "contact": {
      "name": "[email protected]"
    }
  },
  "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"
            }
          }
        }
      }
    }
  }
}
35
John P

Sie stellen tatsächlich mehrere Fragen in einer, und ich werde versuchen, sie alle zu beantworten.

In Swagger 1.2 und früheren Versionen war das Aufteilen von Dateien obligatorisch und künstlich. Es war als eine Möglichkeit gedacht, Operationen zu gruppieren, und Swagger 2.0 bietet eine alternative Methode, um dies zu tun (mehr dazu bald).

Swagger 2.0 ist in der Tat eine einzelne Datei, die externe Dateien überall dort zulässt, wo $ref wird genutzt. Sie können einen einzelnen Dienst nicht in mehrere Dateien aufteilen und als eine Datei kombinieren, aber Sie können Operationen für bestimmte Pfade extern angeben (ebenfalls mit dem Befehl $ref Eigentum).

Wir sind derzeit dabei, die Möglichkeit zu finalisieren, mehrere Mikrodienste in einer einzigen Sammlung zusammenzufassen, aber letztendlich wird jeder Mikrodienst immer noch eine einzelne Datei sein.

Wie bereits erwähnt, hat sich die Gruppierung von Operationen in Swagger 2.0 geändert und das Konzept einer 'Ressource' existiert nicht mehr. Stattdessen gibt es Tags (mit dem "tags" Eigenschaft), die pro Operation zugewiesen werden kann. Das tags ist ein Array von Werten, und im Gegensatz zu früheren Versionen kann jede Operation bei Bedarf unter mehreren Tags vorhanden sein. In Swagger-UI werden alle Vorgänge, für die keine Tags definiert sind, unter dem Tag default abgelegt. Dies ist das Verhalten, das Sie gesehen haben. Es gibt eine zusätzliche tags -Eigenschaft im Objekt der obersten Ebene, mit der Sie Beschreibungen zu Tags hinzufügen und deren Reihenfolge festlegen können. Sie muss jedoch nicht zwingend angegeben werden.

Abschließend habe ich keine Ahnung, wie das json-Schema von Swagger 2.0 zu http://json.schemastore.org/swagger-2. kam, aber es ist sicherlich nicht auf dem neuesten Stand. Das aktuellste Schema finden Sie hier - http://swagger.io/v2/schema.json - und es befindet sich noch in der Entwicklung. Beachten Sie, dass die Quelle der Wahrheit die Spezifikation ( https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md ) und nicht das Schema ist. Im Falle von Konflikten gewinnt die Spezifikation.

Bearbeiten:

Wir haben gerade einen Leitfaden zum Referenzieren veröffentlicht. Dies kann in einigen Anwendungsfällen hilfreich sein - https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md

27
Ron

Ich habe darüber in diesem Blog-Beitrag geschrieben. Sie können grundsätzlich die Bibliothek JSON Refs verwenden, um alle Ihre kleinen Swagger-Dateien in eine große aufzulösen und in den Tools zu verwenden.

10
Mohsen

Wenn die JSON-Refs bei Ihnen nicht funktioniert haben, ist es möglicherweise hilfreich, einen eigenen Verkettungssatz zu schreiben. Nun, anstatt Ihre eigenen zu schreiben, können Sie tatsächlich etwas verwenden, das bereits da draußen ist. Jede Template-Engine wird es tun. In meinem Fall hat sich herausgestellt, dass Lenker sehr hilfreich sind (da Lenker tatsächlich die Einrückung beibehalten, was für Yaml-Dateien perfekt ist, da bei ihnen die Groß- und Kleinschreibung beachtet wird).

Dann können Sie ein Build-Skript in Node haben:

'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());

Lesen Sie mehr zum Thema auf meinem Blog .

2
Oleg Berman

Beachten Sie, dass RepreZen API Studio jetzt Swagger/Open API-Projekte mit mehreren Dateien über die hier beschriebene Syntax $ref Unterstützt. So können Sie große Swagger-Projekte in Module aufteilen, um die Wiederverwendung und Teamzusammenarbeit zu ermöglichen. Sie können dann den integrierten Swagger-Normalisierer verwenden, um eine einzelne, konsolidierte Swagger-Datei zu erstellen, wenn Sie Ihr API-Modell außerhalb der Design-/Entwicklungsumgebung verwenden müssen.

Hinweis: Im Interesse der vollständigen Offenlegung bin ich Produktmanager bei RepreZen. Ich bin letzte Woche über diesen Thread gestolpert und dachte, ich würde mitmachen.

2
daffinm

Ich habe einen Swagger/OpenAPI-Präprozessor geschrieben, um das Verfassen von Spezifikationen zu vereinfachen.

https://github.com/dolmen-go/openapi-preprocessor/

Insbesondere unterstützt es $ref verweist auf externe Dateien und ermöglicht das Bearbeiten Ihrer Spezifikation als mehrere Dateien, es wird jedoch eine einzelne Datei erstellt, um maximale Kompatibilität mit Tools zu gewährleisten, die diese Dateien verwenden.

1
dolmen

Ich versuche das auch herauszufinden und es gibt einige nützliche Informationen in der Swagger Google Gruppe . Es sieht so aus, als ob der Konsens darin besteht, dass Sie die Definitionen in separate Dateien aufteilen können, solange $ ref auf eine absolute URL verweist. Beispiel hier:

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

1
Bailey Smith

Wenn json bei dir nicht funktioniert, kannst du auch und du verwendest node.js, du kannst auch module.exports

Ich habe meine Definitionen in Modulen und kann ein Modul innerhalb eines Moduls anfordern:

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


...
0
Samuel