Öffnen Sie API-Spezifikationen mit mehr als einer YAML-Datei

Jeder, der jemals eine REST-API dokumentiert hat, weiß, wie es sich anfühlt, eine ganze YAML-Datei mit all diesen Ressourcen, Pfaden, Anforderungen und Schemata zu schreiben, aber plötzlich merkt man, dass man eine behält Datei, in der die letzte Zeile 5 Ziffern lang ist. Ja, es ist schmerzhaft.

Da die besten Anwendungen diejenigen sind, die wir selbst entwickelt haben, befand ich mich genau an dieser Stelle und dokumentierte eine API bei der Arbeit. Ich habe viel gesucht, aber keine einzige praktikable Lösung für dieses Problem gefunden. Da kommen unsere Programmierinstinkte ins Spiel und wir verbringen fünfmal so viel Zeit damit, ein neues Werkzeug für uns selbst zu bauen. Genau das habe ich getan und möchte Ihnen allen ein brandneues, in Go geschriebenes Tool vorstellen, mit dem Sie Ihre YAML-Dateien in einer einzigen Boss-Datei zusammenführen können, um sie als Ihre OpenAPI-Spezifikation zu verwenden.

Wir stellen vor: GOpenAPI

GOpenAPI (Golang OpenAPI) ist ein Tool, das eine Datei namens dirs.json verwendet, um Dateien und Verzeichnisse (ja, ganze Verzeichnisse im Yaml-Format) am Ende der Ausführung in eine einzige swagger.yaml-Datei zu scannen.

Sie können den Quellcode hier überprüfen. Beachten Sie, dass das Repository auch eine Vorlage ist, die geklont und als Entwurf verwendet werden kann, um mit diesem Tool Ihre erste OpenAPI-Spezifikation zu erstellen (stellen Sie nur sicher, dass Sie den Gopenapi-Ordner behalten, wenn Sie nicht bereit sind, ihn über go install zu installieren, andernfalls ist er vollständig abnehmbar)

Wie funktioniert es (und bekomme ich es zum Laufen)?

Einfach: Sobald Sie gopenapi ausführen, liest es die Datei dirs.json und beginnt mit der Erstellung einer OpenAPI-Spezifikation mit allen darin deklarierten Dateien und Ordnern. Beachten Sie, dass dirs.json Dateien für eindeutige Schlüssel wie Informationen, Server und Sicherheit sowie einen Schlüssel namens „Template“ verwendet (bei dem es sich nur um eine leere OpenAPI-YAML-Datei handelt)

Ressourcen und Schlüssel, die schwer in einer einzigen Datei gespeichert werden können (z. B. Pfade, Schemata und Anforderungen), können in Ordnern gespeichert werden, und diese können auch mit dem gemeinsamen #ref-Tag auf OpenAPI erwähnt werden, da dies bei allen der Fall ist Gehen Sie nach dem Zusammenführen zur gleichen Datei.

Dieses Projekt verfügt außerdem über eine index.html, die statisch bereitgestellt werden kann und außerdem mit dem offiziellen Swagger UI-Bundle interagiert, das im dist-Ordner enthalten ist.

Das ist alles, Leute

Ich hoffe, dass dieses Tool für jeden geeignet ist, der (genau wie ich) viele Reddits- und Github-Repositories durchsucht hat, nur um nicht das gesuchte Tool zu finden. Nun, jetzt haben Sie es und es ist völlig Open Source, was bedeutet, dass ich, wenn Sie eine Verbesserung oder ein Problem sehen, das gelöst werden kann, nicht zweimal darüber nachdenken werde, mit Ihnen zusammenzuarbeiten, um es zu lösen. Außerdem bin ich ziemlich naiv, was Golang angeht, daher könnte es bei diesem Projekt viel zu verbessern geben. Ich werde versuchen, es auf dem neuesten Stand zu halten und es ständig zu verbessern (da ich es jetzt auch häufig verwenden werde)

Vielen Dank fürs Lesen und ich hoffe, dass es Ihnen genauso nützlich ist wie mir ;)

Das obige ist der detaillierte Inhalt vonÖffnen Sie API-Spezifikationen mit mehr als einer YAML-Datei. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!