Zum Hauptinhalt springen

Generierung von Swagger-Dateien

Übersicht

Wie wir wissen, bietet das Beego-Framework Unterstützung für die Generierung von Swagger-Dateien, um die API über das Befehlszeilenwerkzeug namens "bee" zu klären. Casdoor basiert ebenfalls auf Beego. Wir haben jedoch festgestellt, dass die von bee generierten Swagger-Dateien die APIs nicht mit dem "@Tag"-Label kategorisieren konnten. Daher haben wir das ursprüngliche bee modifiziert, um diese Funktion zu implementieren.

Wie man den Kommentar schreibt

Die meisten Regeln sind genau identisch mit den ursprünglichen bee Kommentarformaten. Die einzige Abweichung besteht darin, dass die API gemäß dem "@Tag"-Label in verschiedene Gruppen eingeteilt werden soll. Daher sind Entwickler verpflichtet, sicherzustellen, dass dieses Tag korrekt hinzugefügt wird. Hier ist ein Beispiel:

// @Title Login
// @Tag Login API
// @Description login
// @Param oAuthParams query string true "oAuth parameters"
// @Param body body RequestForm true "Login information"
// @Success 200 {object} controllers.api_controller.Response The Response object
// @router /login [post]
func (c *ApiController) Login() {

APIs mit denselben "@Tag"-Labels werden in dieselbe Gruppe gelegt.

Wie man die Swagger-Datei generiert

  1. Schreiben Sie Kommentare für die API im richtigen Format.

  2. Holen Sie dieses Repository: https://github.com/casbin/bee.

  3. Bauen Sie das modifizierte bee. Zum Beispiel, im Stammverzeichnis von casbin/bee, führen Sie den folgenden Befehl aus:

    go build -o mybee .
  4. Kopieren Sie mybee in das Basisverzeichnis von Casdoor.

  5. In diesem Verzeichnis führen Sie den folgenden Befehl aus:

    mybee generate docs
  6. (Optional) Wenn Sie Swagger-Dokumente für bestimmte Tags oder APIs generieren möchten, finden Sie hier einige Beispielbefehle:

    mybee generate docs --tags "Adapter API"
    mybee generate docs --tags "Adapter API,Login API"
    mybee generate docs --apis "add-adapter"
    mybee generate docs --apis "add-adapter,delete-adapter"

    Beachtenswert: Wir akzeptieren nur ein Komma , als Trennzeichen, wenn mehrere Tags/APIs angegeben werden.

Dann werden Sie feststellen, dass die neuen Swagger-Dateien generiert werden.