Generieren Sie API-Spezifikationen mit GO / Gin Gin-Swagger

Vorwort

Dieser Artikel fasst die Erkenntnisse zum Generieren von API-Spezifikationen für Gin-Produkte unter Verwendung der Gin-Swagger-Bibliothek zusammen. Link zum Gin-Swagger-Repository

Erstellen Sie ein Produkt zum Testen

Erstellen Sie einen Ordner

//In jedem Verzeichnis
$ mkdir use_swagger && cd use_swagger

Go mod initialisieren

$ go mod init use_swagger

Bibliotheksinstallation

$ go get -u github.com/gin-gonic/gin
$ go get -u github.com/swaggo/swag/cmd/swag
$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files

Überprüfen Sie die Version nach Abschluss der Installation.

$ swag -v
swag version v1.6.7

Aktuelle Verzeichnisstruktur

|-- use_swagger
|-- |-- go.mod

Dem Produkt hinzugefügte API-Spezifikationen

Erstellen Sie eine main.go-Datei im Verzeichnis use_swagger

$ touch main.go

Vor dem Hinzufügen

main.go

package main

import (
	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.New()	
	r.GET("/test", test)	
	r.Run()
}

func test(c *gin.Context){
	c.JSON(http.StatusOK, gin.H{ "msg": "ok"})
}

Wenn Sie nach dem Starten des Servers auf "http: // localhost: 8080 / test" zugreifen, werden einfache Json-Daten zurückgegeben.

Nach Zugabe

main.go

package main

import (
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	"github.com/swaggo/gin-swagger"
	"net/http"

	_ "use_swagger/docs"
)

// @Titel API-Dokumenttitel
// @version version(1.0)
// @Beschreibung Beschreibung der Spezifikationen
// @Vorsichtsmaßnahmen bei der Verwendung von TermsOfService-Spezifikationen

// @contact.Name API-Unterstützer
// @contact.url http://www.swagger.io/support
// @contact.email [email protected]

// @license.Namenslizenz(Verpflichtend)
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /
func main() {
	r := gin.New()

	url := ginSwagger.URL("http://localhost:8080/swagger/doc.json")
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
	
	r.GET("/test", test)
	r.Run()
}

// @Beschreibung Test-API-Details
// @version 1.0
// @accept application/x-json-stream
// @param none query string false "Nicht benötigt."
// @Success 200 {object} gin.H {"code":200,"msg":"ok"}
// @router /test/ [get]
func test(c *gin.Context){
	c.JSON(http.StatusOK, gin.H{ "msg": "ok"})
}

Initialisieren Sie die Spezifikationen.

$ swag init

Nach Abschluss der Initialisierung sieht die Verzeichnisstruktur wie folgt aus.

|-- use_swagger
|-- |-- docs
|-- |-- |-- docs.go
|-- |-- |-- swagger.json
|-- |-- |-- swagger.yaml
|-- |-- main.go
|-- |-- go.mod

Starten Sie den Server und greifen Sie auf "http: // localhost: 8080 / swagger / index.html" zu, um die Spezifikationen anzuzeigen. Ich werde es tatsächlich verwenden, die Parameter entsprechend übergeben und ausführen. Ich habe die erwartete Antwort erhalten.

Häufig verwendete Optionen

API-Optionen

Nutzungslegende

// @Summary Auth admin
// @Description get admin info
// @Tags accounts,admin
// @Accept  application/x-json-stream
// @Produce  application/x-json-stream
// @Success 200 {object} model.Admin
// @Failure 400 {object} httputil.HTTPError
// @Failure 401 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Security ApiKeyAuth
// @Router /admin/auth [post]
func (c *Controller) Auth(ctx *gin.Context) {
	authHeader := ctx.GetHeader("Authorization")
	if len(authHeader) == 0 {
		httputil.NewError(ctx, http.StatusBadRequest, errors.New("please set Header Authorization"))
		return
	}
	if authHeader != "admin" {
		httputil.NewError(ctx, http.StatusUnauthorized, fmt.Errorf("this user isn't authorized to operation key=%s expected=admin", authHeader))
		return
	}
	admin := model.Admin{
		ID:   1,
		Name: "admin",
	}
	ctx.JSON(http.StatusOK, admin)
}

// ShowBottle godoc
// @Summary Show a bottle
// @Description get string by ID
// @ID get-string-by-int
// @Tags bottles
// @Accept  json
// @Produce  json
// @Param  id path int true "Bottle ID"
// @Success 200 {object} model.Bottle
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /bottles/{id} [get]
func (c *Controller) ShowBottle(ctx *gin.Context) {
	id := ctx.Param("id")
	bid, err := strconv.Atoi(id)
	if err != nil {
		httputil.NewError(ctx, http.StatusBadRequest, err)
		return
	}
	bottle, err := model.BottleOne(bid)
	if err != nil {
		httputil.NewError(ctx, http.StatusNotFound, err)
		return
	}
	ctx.JSON(http.StatusOK, bottle)
}

Weitere API-Informationen sind Offizielles Dokument und Dieses Repository. Bitte beziehen Sie sich auf Master / Beispiel / Celler / Controller.

Eindrücke von der Nutzung

Die Gin-Swagger-Bibliothek ist nicht sehr nützlich, da es sich um eine API-Spezifikation handelt, die aus Kommentaren generiert wird. Achten Sie beim Schreiben darauf, dass keine Fehler vorliegen. : point_up_tone1: