Ich definiere gerade eine Rest-API und ich beabsichtige, Swagger zu verwenden, um sie zu dokumentieren. Ich habe bereits damit begonnen, meine API-Spezifikationen mit der Open API-Spezifikation in YAML im Swagger-Editor zu definieren.
Dann verstehe ich, dass ich diese Datei dem Swagger-Codegen zur Verfügung stellen werde, um eine Server-Implementierung und auch die Swagger-UI zu erstellen (deren statische Dateien zuvor auf meinen Server kopieren), um die interaktive Dokumentation anzuzeigen.
Laut Swagger ist dies der Top-down-Ansatz .
Aber später werde ich wahrscheinlich diese API modifizieren müssen, und ich möchte es durch diese langweilige YAML-Datei, die vorher definiert wurde, machen, um die API leicht von jedem (und sprachunabhängig) modifizierbar zu machen.
Und wenn ich den Bottom-up-Ansatz (über die Swagger-core -Anmerkung) gewählt habe, werde ich alle weiteren Änderungen im Code des Implementierungsservers zurückhalten , und meine ursprüngliche Definitionsdatei wird nie wieder verwendbar sein.
Danke für Ihre Bedenken.
Um die API-Dokumentation zu erhalten, ist das beste Vorgehen, das ich vorschlagen kann, ein hybrider Ansatz.
Wenn Sie zuerst die Bulk-Entwicklung durchführen müssen, gehen Sie nach dem Top-Down-Ansatz. Dies reduziert den anfänglichen Einstellungs- und Codierungsaufwand. Das ist die Grundidee hinter jedem Codegen.
Wenn es darum geht, die APIs zu pflegen oder jeden Tag (oder jede Woche) ein paar neue hinzuzufügen, folgen Sie dem Bottom-up-Ansatz. Sie haben bereits den vorherigen Code, das einzige, was Sie tun müssen, ist, weitere Annotationen oder API-Definitionen hinzuzufügen.
Wenn Sie von oben nach unten gehen, wird der Zweck der Codewartung iterativ vereitelt. Kesselplatten und selbst generierter Code geben Ihnen einen schnellen Start, nicht für den Unterhalt.
Meine Meinung kann voreingenommen sein.
Für den API-Client sollte in den meisten Fällen keine Anpassung erforderlich sein. Wenn Sie feststellen, dass Sie es an Ihre Anforderungen anpassen müssen, kann es sinnvoll sein, über Ссылка (und bitte überprüfen Sie, welche Optionen zur Anpassung der Ausgabe zur Verfügung stehen, zB für PHP, führen Sie java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php aus)
Bei Server-Stubs müssen sich die Entwickler im Idealfall nur auf die Geschäfts- / Anwendungslogik konzentrieren und den Server-Stub beim Hinzufügen / Löschen / Aktualisieren von Endpunkten neu generieren (aber ich glaube nicht, dass alle Server-Stubs dies erreichen können)
Haftungsausschluss: Ich bin der Top-Beitrag für Swagger Codegen
Tags und Links swagger