Swagger

Einführung

Aufruf

Die Swagger UI ist verfügbar unter https://<url>/api/swagger z.B. unter https://app.dev.green-ecolution.de/api/swagger

Swagger Definitionen

Route definieren

Um in Swagger eine Route zu definieren, wird im Code zu dem Handler der Route folgende Kommentare gesetzt, welche swaggo/swag intepretiert. Anbei ein beispiel für die Route /info

// @Summary		Get info about the app
// @Description		Get info about the app and the server
// @Id			get-app-info
// @Tags		Info
// @Produce		json
// @Success		200	{object}	info.AppInfoResponse
// @Failure		400	{object}	HTTPError
// @Failure		401	{object}	HTTPError
// @Failure		403	{object}	HTTPError
// @Failure		404	{object}	HTTPError
// @Failure		500	{object}	HTTPError
// @Router		/info [get]
func GetAppInfo(svc service.InfoService) fiber.Handler {
	// ...
}

Entitäten definieren

Swagger versteht die Entitäten, welche in der Route referenziert wird automatisch. Es ist dennoch gut, den Namen anzupassen, um den package Name von go nicht zu übernehmen. So würde das Objekt in Swagger mit info.AppInfoResponse aufgerufen werden. Mit dem Kommentar // @Name AppInfo aus dem lagen Namen, nützlich in der Anwendung einen kurzen Namen, welcher besser für die Aussenwelt passt. Das Objekt im Code sieht wie folgt aus:

type AppInfoResponse struct {
	Version   string         `json:"version"`
	BuildTime string         `json:"buildTime"`
	GoVersion string         `json:"goVersion"`
	Git       GitResponse    `json:"git"`
	Server    ServerResponse `json:"server"`
} // @Name AppInfo