Swaggo零基礎(chǔ)入門教程
配置流程
注意區(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
- 在當前文件夾下打開命令行,輸入
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)境變量配置完畢
初始化
進入項目根目錄,保證當前目錄下存在至少一個 go 文件(比如主入口文件 main.go
)
當前目錄下打開命令行,輸入 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)文章希望大家以后多多支持腳本之家!
相關(guān)文章
xorm根據(jù)數(shù)據(jù)庫生成go model文件的操作
這篇文章主要介紹了xorm根據(jù)數(shù)據(jù)庫生成go model文件的操作,具有很好的參考價值,希望對大家有所幫助。一起跟隨小編過來看看吧2020-12-12如何使用工具自動監(jiān)測SSL證書有效期并發(fā)送提醒郵件
本文介紹了如何開發(fā)一個工具,用于每日檢測SSL證書剩余有效天數(shù)并通過郵件發(fā)送提醒,工具基于命令行,通過SMTP協(xié)議發(fā)送郵件,需配置SMTP連接信息,本文還提供了配置文件樣例及代碼實現(xiàn),幫助用戶輕松部署和使用該工具2024-10-10