So installieren Sie Swag, um eine Golang-API-Dokumentation zu generieren

Swag ist ein Tool zum schnellen Erstellen von Go-Anwendungen, das automatisch Swagger-Dokumentation generiert. Entwickler können automatisch eine API-Dokumentation generieren, indem sie einfach einige Kommentare zu ihrem Code hinzufügen. Swag unterstützt die Generierung von API-Dokumenten gemäß RESTful-API-Standards sowie die Generierung von Markdown- und HTML-Formaten.

In diesem Artikel stellen wir vor, wie man Swag in Golang installiert und verwendet.

Schritt 1 – Swag installieren

Swag kann von GitHub aus mit dem Befehl „go get“ installiert werden. Verwenden Sie den folgenden Befehl, um Swag zu installieren:

$ go get github.com/swaggo/swag/cmd/swag

Nachdem die Installation abgeschlossen ist, finden Sie die Binärdatei „swag“ im $GOPATH /bin-Pfad. Jetzt können wir Swag weiterhin zum Generieren der API-Dokumentation verwenden.

Schritt 2 – API-Dokumentation generieren

Swag erfordert einige spezielle Codekommentare, um die API-Dokumentation korrekt zu generieren. Hier sind einige Beispielkommentare:

// @Summary 创建用户
// @Description 创建一个新用户
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 200 {string} string "成功"
// @Failure 400 {string} string "请求错误"
// @Failure 500 {string} string "服务器内部错误"
// @Router /users [post]
func CreateUser(c *gin.Context) {
    // ...
}

Die obigen Kommentare beschreiben eine API zum Erstellen eines Benutzers. Swag sucht im Code nach diesen speziellen Kommentaren und erstellt dann die Dokumentation.

Führen Sie den folgenden Befehl aus, um Dokumentation zu generieren:

$ swag init

Dadurch wird Ihre Anwendung gescannt und Swagger-JSON-Dateien und die Swagger-Benutzeroberfläche generiert.

Schritt 3 – Swagger-Benutzeroberfläche hinzufügen

Swagger-Benutzeroberfläche bietet eine interaktive Schnittstelle zum Anzeigen und Testen von APIs. Wir können Swagger UI zu unserer Webanwendung hinzufügen.

// main.go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/swaggo/files" // swagger embed files
    "github.com/swaggo/gin-swagger" // gin-swagger middleware
    _ "github.com/user/repo/docs" // docs is generated by Swag CLI, you have to import it.
)

func main() {
    r := gin.New()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    //...
}

Angenommen, Sie haben die Dokumentation mit Swag generiert. Jetzt können Sie die API-Dokumentation anzeigen, indem Sie den folgenden Link in Ihrem Browser öffnen:

http://localhost:8080/swagger/index.html

Dies ist die Web-Benutzeroberfläche von Swagger, mit der Sie die API anzeigen und testen können.

Zusammenfassung

In diesem Artikel haben wir vorgestellt, wie man Swag in Golang installiert und verwendet. Mit den Anmerkungen und Befehlen von Swagger können Sie ganz einfach API-Dokumentation erstellen. Swag macht den gesamten Prozess schnell und einfach und die Dokumentation mit Swag lässt sich gut in die Swagger-Benutzeroberfläche integrieren

Das obige ist der detaillierte Inhalt vonSo installieren Sie Swag, um eine Golang-API-Dokumentation zu generieren. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!