Swaggo零基礎(chǔ)入門教程

更新時間：2023年01月28日 08:50:39 作者：知奕奕

swagger是一套基于OpenAPI規(guī)范構(gòu)建的開源工具，使用RestApi。swagger-ui呈現(xiàn)出來的是一份可交互式的API文檔，可以直接在文檔頁面嘗試API的調(diào)用

配置流程

注意區(qū)分

go-swagger != swaggo

二者功能差不多，都是生成接口文檔用的；

前者構(gòu)建速度極慢且官方文檔極不友好；

后者構(gòu)建速度快且上手簡單，故我們這里采用它；

下載swaggo

項目根目錄下（即與 go.mod 同級的文件夾）命令行執(zhí)行此代碼，下載 swaggo

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

之后就是關(guān)鍵的 swag 環(huán)境變量配置！

進入你之前設(shè)置的 GOPATH 目錄下
進入該文件夾：pkg\mod\github.com\swaggo\swag@v1.8.9\cmd\swag，發(fā)現(xiàn)里面有一個文件 main.go
在當(dāng)前文件夾下打開命令行，輸入 go build 執(zhí)行構(gòu)建過程
構(gòu)建完畢得到 swag.exe ，復(fù)制他
丟到 golang 根目錄下的 bin 文件夾內(nèi)即可（前提是你之前在系統(tǒng)變量 path 里面添加了%GOROOT/bin 這個路徑值，否則你依然需要重新配置一遍系統(tǒng)變量）

更新：對于版本 go1.18+，可以直接使用 go init 代替 go build，這樣做的好處是可以直接省去后面繁瑣的變量配置了

此時在命令行輸入 swag -v 后可以看見版本號則表示環(huán)境變量配置完畢

初始化

進入項目根目錄，保證當(dāng)前目錄下存在至少一個 go 文件（比如主入口文件 main.go）

當(dāng)前目錄下打開命令行，輸入 swag init 即可根據(jù) go 文件自動構(gòu)建 swagger 文檔了；

新生成的文檔存放在 docs 文件夾下

快速上手

gin-swagger

官方參考文檔https://github.com/swaggo/gin-swagger

項目根目錄執(zhí)行代碼安裝依賴：

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

簡單測試

在測試前務(wù)必先執(zhí)行 swag init 生成對應(yīng) docs 文件！

import 內(nèi)需要手動導(dǎo)入 docs，其余的兩個包 goland 會自動處理

通過注釋編寫接口信息，然后于 main 方法注冊 swagger-ui 的界面路由就完畢了

package main
import (
    // 這里需要我們手動導(dǎo)入docs，不然報錯
    // 因為該包我們沒有在代碼中實際引用到，故別名需要取名為下劃線
	_ "ginoj/docs"
	"github.com/gin-gonic/gin"
    // 這兩個是固定的，不用修改直接復(fù)制黏貼導(dǎo)包
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	"net/http"
)
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context) {
	g.JSON(http.StatusOK, "helloworld")
}
func main() {
	router := gin.Default()
    // 注冊swagger-ui界面路由
	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
	router.Run(":10001")
}

此時進入localhost:8080/swagger/index.html 就可以看見接口文檔了（注意這里的端口修改為你使用的那一個！）

詳細配置

通過上述操作我們發(fā)現(xiàn)依然會提示缺失了 spec 文件，這是我們沒有執(zhí)行 init 的緣故；

注意，每次修改一次文檔都必須執(zhí)行 swag init 一次，并且重啟服務(wù)器才可以正常渲染；

我們把 main.go 改造為這個樣子，為 main 添加了一些全局注釋

package main
import (
	_ "ginoj/docs"
	"github.com/gin-gonic/gin"
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	"net/http"
)
// Helloworld
// @Description a simple example
// @Tags example
// @Accept json
// @Produce json
// @Param id path int true "shit"
// @Success 200 {string} json "{"status":"success"}"
// @Router /helloworld [get]
func Helloworld(g *gin.Context) {
	g.JSON(http.StatusOK, "helloworld")
}
// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/
// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io
// @license.name  MIT
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
// @host      localhost:10001
func main() {
	router := gin.Default()
	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
	router.Run(":10001")
}

回到根目錄下執(zhí)行 swag init，之后重啟服務(wù)器即可看到文檔了

到此這篇關(guān)于Swaggo零基礎(chǔ)入門教程的文章就介紹到這了,更多相關(guān)Swaggo入門內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: