網(wǎng)站首頁(yè) 編程語(yǔ)言 正文
前言
這篇文章主要介紹了Go語(yǔ)言使用swagger生成接口文檔的方法，希望能夠?qū)Υ蠹业膶W(xué)習(xí)或工作具有一定的幫助,需要的朋友可以參考下。
在前后端分離的項(xiàng)目開(kāi)發(fā)過(guò)程中，如果后端同學(xué)能夠提供一份清晰明了的接口文檔，那么就能極大地提高大家的溝通效率和開(kāi)發(fā)效率。那如何維護(hù)接口文檔，歷來(lái)都是令人頭痛的，感覺(jué)很浪費(fèi)精力，而且后續(xù)接口文檔的維護(hù)也十分耗費(fèi)精力。在很多年以前，也流行用word等工具寫(xiě)接口文檔，這里面的問(wèn)題很多，如格式不統(tǒng)一、后端人員消費(fèi)精力大、文檔的時(shí)效性也無(wú)法保障。
針對(duì)這類(lèi)問(wèn)題，最好是有一種方案能夠既滿足我們輸出文檔的需要又能隨代碼的變更自動(dòng)更新，Swagger正是那種能幫我們解決接口文檔問(wèn)題的工具。
Swagger介紹
Swagger是基于標(biāo)準(zhǔn)的 OpenAPI 規(guī)范進(jìn)行設(shè)計(jì)的，本質(zhì)是一種用于描述使用json表示的Restful Api的接口描述語(yǔ)言，只要照著這套規(guī)范去編寫(xiě)你的注解或通過(guò)掃描代碼去生成注解，就能生成統(tǒng)一標(biāo)準(zhǔn)的接口文檔和一系列 Swagger 工具。Swagger包括自動(dòng)文檔，代碼生成和測(cè)試用例生成。
1、安裝
go get -u github.com/swaggo/swag/cmd/swag
在macOS中安裝 swag需要執(zhí)行如下命令：
mv $GOPATH/bin/swag /usr/local/go/bin
2、檢測(cè)是否安裝成功
$ swag -v
swag version v1.8.4
3、安裝gin-swagger擴(kuò)展
$ go get -u -v github.com/swaggo/gin-swagger
$ go get -u -v github.com/swaggo/files
$ go get -u -v github.com/alecthomas/template
使用
使用gin-swagger為你的代碼自動(dòng)生成接口文檔，一般需要下面三個(gè)步驟：
- 按照swagger要求給接口代碼添加聲明式注釋。
- 使用swag工具掃描代碼自動(dòng)生成api接口文檔數(shù)據(jù)。
- 使用gin-swagger渲染在線接口文檔頁(yè)面。
1、添加注釋
go-swapper注解規(guī)范說(shuō)明：
注：注解詳情可參見(jiàn)官網(wǎng)文檔Swagger Documentation
| 注解 | 描述 |
|---|---|
| @Summary | 摘要 |
| @Produce | API 可以產(chǎn)生的 MIME 類(lèi)型的列表，MIME 類(lèi)型你可以簡(jiǎn)單的理解為響應(yīng)類(lèi)型，例如：json、xml、html 等等 |
| @Param | 參數(shù)格式，從左到右分別為：參數(shù)名、入?yún)㈩?lèi)型、數(shù)據(jù)類(lèi)型、是否必填、注釋 |
| @Success | 響應(yīng)成功，從左到右分別為：狀態(tài)碼、參數(shù)類(lèi)型、數(shù)據(jù)類(lèi)型、注釋 |
| @Failure | 響應(yīng)失敗，從左到右分別為：狀態(tài)碼、參數(shù)類(lèi)型、數(shù)據(jù)類(lèi)型、注釋 |
| @Router | 路由，從左到右分別為：路由地址，HTTP 方法 |
示例demo：
package main
import (
"github.com/gin-gonic/gin"
"github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "github/mwqnice/swag/docs" // 千萬(wàn)不要忘了導(dǎo)入把你上一步生成的docs
)
type Article struct{
ID uint32 `gorm:"primary_key" json:"id"`
CreatedBy string `json:"created_by"`
ModifiedBy string `json:"modified_by"`
CreatedOn uint32 `json:"created_on"`
ModifiedOn uint32 `json:"modified_on"`
DeletedOn uint32 `json:"deleted_on"`
IsDel uint8 `json:"is_del"`
Title string `json:"title"`
Desc string `json:"desc"`
Content string `json:"content"`
CoverImageUrl string `json:"cover_image_url"`
State uint8 `json:"state"`
}
func NewArticle() Article {
return Article{}
}
func main() {
r := gin.Default()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run(":8088")
}
// @Summary 獲取單個(gè)文章
// @Produce json
// @Param id path int true "文章ID"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請(qǐng)求錯(cuò)誤"
// @Failure 500 {object} string "內(nèi)部錯(cuò)誤"
// @Router /api/v1/articles/{id} [get]
func (a Article) Get(c *gin.Context) {
}
// @Summary 獲取多個(gè)文章
// @Produce json
// @Param name query string false "文章名稱"
// @Param tag_id query int false "標(biāo)簽ID"
// @Param state query int false "狀態(tài)"
// @Param page query int false "頁(yè)碼"
// @Param page_size query int false "每頁(yè)數(shù)量"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請(qǐng)求錯(cuò)誤"
// @Failure 500 {object} string "內(nèi)部錯(cuò)誤"
// @Router /api/v1/articles [get]
func (a Article) List(c *gin.Context) {
return
}
// @Summary 創(chuàng)建文章
// @Produce json
// @Param tag_id body string true "標(biāo)簽ID"
// @Param title body string true "文章標(biāo)題"
// @Param desc body string false "文章簡(jiǎn)述"
// @Param cover_image_url body string true "封面圖片地址"
// @Param content body string true "文章內(nèi)容"
// @Param created_by body int true "創(chuàng)建者"
// @Param state body int false "狀態(tài)"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請(qǐng)求錯(cuò)誤"
// @Failure 500 {object} string "內(nèi)部錯(cuò)誤"
// @Router /api/v1/articles [post]
func (a Article) Create(c *gin.Context) {
}
// @Summary 更新文章
// @Produce json
// @Param tag_id body string false "標(biāo)簽ID"
// @Param title body string false "文章標(biāo)題"
// @Param desc body string false "文章簡(jiǎn)述"
// @Param cover_image_url body string false "封面圖片地址"
// @Param content body string false "文章內(nèi)容"
// @Param modified_by body string true "修改者"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請(qǐng)求錯(cuò)誤"
// @Failure 500 {object} string "內(nèi)部錯(cuò)誤"
// @Router /api/v1/articles/{id} [put]
func (a Article) Update(c *gin.Context) {
return
}
// @Summary 刪除文章
// @Produce json
// @Param id path int true "文章ID"
// @Success 200 {string} string "成功"
// @Failure 400 {object} string "請(qǐng)求錯(cuò)誤"
// @Failure 500 {object} string "內(nèi)部錯(cuò)誤"
// @Router /api/v1/articles/{id} [delete]
func (a Article) Delete(c *gin.Context) {
return
}
2、生成接口文檔數(shù)據(jù)
格式化swag注解
$ swag fmt
在項(xiàng)目根目錄執(zhí)行以下命令，使用swag工具生成接口文檔數(shù)據(jù)。
$ swag init
執(zhí)行完上述命令后，如果你寫(xiě)的注釋格式?jīng)]問(wèn)題，此時(shí)你的項(xiàng)目根目錄下會(huì)多出一個(gè)docs文件夾。
./docs
├── docs.go
├── swagger.json
└── swagger.yaml
3、引入gin-swagger渲染文檔數(shù)據(jù)
然后在項(xiàng)目代碼中注冊(cè)路由的地方按如下方式引入gin-swagger相關(guān)內(nèi)容：
import (
"github.com/gin-gonic/gin"
"github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "github/mwqnice/swag/docs" // 千萬(wàn)不要忘了導(dǎo)入把你上一步生成的docs
)
//添加swagger訪問(wèn)路由
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
啟動(dòng)項(xiàng)目，在瀏覽器中輸入地址：http://127.0.0.1:8088/swagger/index.html
總結(jié)
到此這篇關(guān)于go語(yǔ)言使用swagger生成接口文檔的文章就介紹到這了, 希望可以對(duì)你的開(kāi)發(fā)有一定幫助。
原文鏈接：https://juejin.cn/post/7126802030944878600
相關(guān)推薦
- 2022-05-13 Android水波紋效果
- 2022-12-11 教你使用MongoDB導(dǎo)入導(dǎo)出備份數(shù)據(jù)_MongoDB
- 2022-04-11 C#定時(shí)任務(wù)框架Quartz.NET介紹與用法_C#教程
- 2022-03-15 .Net?Core?SDK命令介紹及使用_自學(xué)過(guò)程
- 2022-04-12 .NET 6 ‘Unable to configure HTTPS endpoint...
- 2022-07-24 .Net行為型設(shè)計(jì)模式之職責(zé)鏈模式（Chain?of?Responsibility）_基礎(chǔ)應(yīng)用
- 2022-06-07 SQL?Server內(nèi)存機(jī)制詳解_MsSql
- 2022-08-22 Python中可以用三種方法判斷文件是否存在_python
- 最近更新
-
- window11 系統(tǒng)安裝 yarn
- 超詳細(xì)win安裝深度學(xué)習(xí)環(huán)境2025年最新版（
- Linux 中運(yùn)行的top命令 怎么退出？
- MySQL 中decimal 的用法？ 存儲(chǔ)小
- get 、set 、toString 方法的使
- @Resource和 @Autowired注解
- Java基礎(chǔ)操作-- 運(yùn)算符，流程控制 Flo
- 1. Int 和Integer 的區(qū)別，Jav
- spring @retryable不生效的一種
- Spring Security之認(rèn)證信息的處理
- Spring Security之認(rèn)證過(guò)濾器
- Spring Security概述快速入門(mén)
- Spring Security之配置體系
- 【SpringBoot】SpringCache
- Spring Security之基于方法配置權(quán)
- redisson分布式鎖中waittime的設(shè)
- maven:解決release錯(cuò)誤：Artif
- restTemplate使用總結(jié)
- Spring Security之安全異常處理
- MybatisPlus優(yōu)雅實(shí)現(xiàn)加密？
- Spring ioc容器與Bean的生命周期。
- 【探索SpringCloud】服務(wù)發(fā)現(xiàn)-Nac
- Spring Security之基于HttpR
- Redis 底層數(shù)據(jù)結(jié)構(gòu)-簡(jiǎn)單動(dòng)態(tài)字符串（SD
- arthas操作spring被代理目標(biāo)對(duì)象命令
- Spring中的單例模式應(yīng)用詳解
- 聊聊消息隊(duì)列，發(fā)送消息的4種方式
- bootspring第三方資源配置管理
- GIT同步修改后的遠(yuǎn)程分支
提供CDN加速