Verwenden Sie OpenAPI/Swagger, um API-Dokumente in der Go-Sprache zu schreiben

Mit der kontinuierlichen Weiterentwicklung der Internettechnologie ist in den letzten Jahren die Bedeutung von Web-API-Schnittstellen immer wichtiger geworden und das Schreiben von API-Dokumenten ist zu einem wichtigen Bestandteil der Entwicklungsarbeit geworden. In der Go-Sprache können wir OpenAPI/Swagger verwenden, um API-Dokumente zu schreiben.

OpenAPI/Swagger ist eine API-Spezifikation und Toolkette, die uns beim Erstellen und Beschreiben von API-Schnittstellen helfen kann, die dem RESTful-Architekturstil entsprechen. Es enthält eine Reihe standardisierter API-Beschreibungssprachen und eine Reihe von Tools, mit denen wir API-Dokumente, Client-Code und Server-Framework automatisch generieren können.

In der Go-Sprache können Sie Swaggers offizielle Go-Implementierung „swag“ verwenden, um schnell API-Dokumente zu generieren. Im Folgenden erfahren Sie, wie Sie mit Swag API-Dokumentation schreiben.

Zuerst müssen wir Swag zum Projekt hinzufügen. Sie können den folgenden Befehl verwenden, um es zum Projekt hinzuzufügen:

go get -u github.com/swaggo/swag/cmd/swag

Nach der Installation von Swag müssen wir Swag-bezogene Pakete in die Datei main.go importieren:

import (
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"
    "github.com/gin-gonic/gin"
)

// 注册swag
func setUpSwagger(engine *gin.Engine) {
    engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

func main() {
    // 初始化 gin 引擎
    engine := gin.Default()
    setUpSwagger(engine)
    router.LoadRouters(engine)
    _ = engine.Run()
}

Als nächstes können wir Swagger-Annotationen in Schnittstellenanmerkungen verwenden, um die Schnittstelle zu beschreiben. Zum Beispiel:

// User register router
// @Summary User register router
// @Description User register router
// @Tags Users
// @Accept  json
// @Produce  json
// @Param user_in body models.NewUser true "user info"
// @Success 200 {string} json "{"code":200,"data":null,"msg":"Register successful"}"
// @Failure 400 {string} json "{"code":400,"msg":"Bad Request"}"
// @Router /users/register [post]
func Register(c *gin.Context) {
    name := c.PostForm("name")
    password := c.PostForm("password")
    ...
}

In den Kommentaren verwenden wir einige prahlerische Anmerkungen:

• @Zusammenfassung: Zusammenfassung der Schnittstelleninformationen
• @Beschreibung: Detaillierte Beschreibung der Schnittstelle
• @Tags: Schnittstellen-Tags
• @Akzeptieren: Inhaltstyp der Schnittstellenanforderung
• @Produzieren: Inhaltstyp der Schnittstellenantwort
• @Param: Beschreibung des Schnittstellenparameters, einschließlich Parameterposition, Parametername, ob es sich um einen erforderlichen Parameter handelt, Parameterbeschreibung und Parameterbeispiel
• @Erfolg: Beschreibung der Schnittstellenerfolgsantwort, Sie können Einschließlich Antwortcode, Antwortinformationen und Antwortdatenstruktur API-Dokument. Das Dokument wird im Dokumentverzeichnis generiert.

swag init

• Jetzt können wir die API-Dokumentation anzeigen, indem wir http://localhost:8080/swagger/index.html besuchen.

Im Allgemeinen kann uns die Verwendung von OpenAPI/Swagger zum Schreiben der API-Dokumentation dabei helfen, die Schnittstelle klarer zu beschreiben und sie leichter lesbar und verständlich zu machen. Die Swag-Bibliothek der Go-Sprache kann schnell API-Dokumente generieren, sodass wir effizienter entwickeln können.

Das obige ist der detaillierte Inhalt vonVerwenden Sie OpenAPI/Swagger, um API-Dokumente in der Go-Sprache zu schreiben. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!