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.