欧美bbbwbbbw肥妇,免费乱码人妻系列日韩,一级黄片

go swagger生成接口文檔使用教程

 更新時間：2022年08月19日 11:41:54   作者：yi個俗人  
這篇文章主要為大家介紹了go swagger生成接口文檔使用教程示例，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪

前言

這篇文章主要介紹了Go語言使用swagger生成接口文檔的方法，希望能夠?qū)Υ蠹业膶W(xué)習(xí)或工作具有一定的幫助,需要的朋友可以參考下。

在前后端分離的項目開發(fā)過程中，如果后端同學(xué)能夠提供一份清晰明了的接口文檔，那么就能極大地提高大家的溝通效率和開發(fā)效率。那如何維護接口文檔，歷來都是令人頭痛的，感覺很浪費精力，而且后續(xù)接口文檔的維護也十分耗費精力。在很多年以前，也流行用word等工具寫接口文檔，這里面的問題很多，如格式不統(tǒng)一、后端人員消費精力大、文檔的時效性也無法保障。

針對這類問題，最好是有一種方案能夠既滿足我們輸出文檔的需要又能隨代碼的變更自動更新，Swagger正是那種能幫我們解決接口文檔問題的工具。

Swagger介紹

Swagger是基于標(biāo)準(zhǔn)的 OpenAPI 規(guī)范進行設(shè)計的，本質(zhì)是一種用于描述使用json表示的Restful Api的接口描述語言，只要照著這套規(guī)范去編寫你的注解或通過掃描代碼去生成注解，就能生成統(tǒng)一標(biāo)準(zhǔn)的接口文檔和一系列 Swagger 工具。Swagger包括自動文檔，代碼生成和測試用例生成。

1、安裝

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

在macOS中安裝 swag需要執(zhí)行如下命令：

mv $GOPATH/bin/swag /usr/local/go/bin

2、檢測是否安裝成功

$ swag -v
swag version v1.8.4

3、安裝gin-swagger擴展

$ 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為你的代碼自動生成接口文檔，一般需要下面三個步驟：

  • 按照swagger要求給接口代碼添加聲明式注釋。
  • 使用swag工具掃描代碼自動生成api接口文檔數(shù)據(jù)。
  • 使用gin-swagger渲染在線接口文檔頁面。

1、添加注釋

go-swapper注解規(guī)范說明：

注：注解詳情可參見官網(wǎng)文檔Swagger Documentation

注解描述
@Summary摘要
@ProduceAPI 可以產(chǎn)生的 MIME 類型的列表，MIME 類型你可以簡單的理解為響應(yīng)類型，例如：json、xml、html 等等
@Param參數(shù)格式，從左到右分別為：參數(shù)名、入?yún)㈩愋?、?shù)據(jù)類型、是否必填、注釋
@Success響應(yīng)成功，從左到右分別為：狀態(tài)碼、參數(shù)類型、數(shù)據(jù)類型、注釋
@Failure響應(yīng)失敗，從左到右分別為：狀態(tài)碼、參數(shù)類型、數(shù)據(jù)類型、注釋
@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" // 千萬不要忘了導(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 獲取單個文章
// @Produce json
// @Param id path int true "文章ID"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請求錯誤"
// @Failure 500 {object} string "內(nèi)部錯誤"
// @Router /api/v1/articles/{id} [get]
func (a Article) Get(c *gin.Context) {
}
// @Summary 獲取多個文章
// @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 "頁碼"
// @Param page_size query int false "每頁數(shù)量"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請求錯誤"
// @Failure 500 {object} string "內(nèi)部錯誤"
// @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 "文章簡述"
// @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 "請求錯誤"
// @Failure 500 {object} string "內(nèi)部錯誤"
// @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 "文章簡述"
// @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 "請求錯誤"
// @Failure 500 {object} string "內(nèi)部錯誤"
// @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 "請求錯誤"
// @Failure 500 {object} string "內(nèi)部錯誤"
// @Router /api/v1/articles/{id} [delete]
func (a Article) Delete(c *gin.Context) {
	return
}

2、生成接口文檔數(shù)據(jù)

格式化swag注解

$ swag fmt

在項目根目錄執(zhí)行以下命令，使用swag工具生成接口文檔數(shù)據(jù)。

$ swag init

執(zhí)行完上述命令后，如果你寫的注釋格式?jīng)]問題，此時你的項目根目錄下會多出一個docs文件夾。

./docs

├── docs.go

├── swagger.json

└── swagger.yaml

3、引入gin-swagger渲染文檔數(shù)據(jù)

然后在項目代碼中注冊路由的地方按如下方式引入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" // 千萬不要忘了導(dǎo)入把你上一步生成的docs
)
//添加swagger訪問路由
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

啟動項目，在瀏覽器中輸入地址：http://127.0.0.1:8088/swagger/index.html

總結(jié)

到此這篇關(guān)于go語言使用swagger生成接口文檔的文章就介紹到這了, 希望可以對你的開發(fā)有一定幫助。

更多關(guān)于go swagger接口文檔的資料請關(guān)注腳本之家其它相關(guān)文章！

相關(guān)文章

  • Go高級特性探究之穩(wěn)定排序詳解

    Go高級特性探究之穩(wěn)定排序詳解

    Go 語言提供了 sort 包，其中最常用的一種是 sort.Slice() 函數(shù),本篇文章將為大家介紹如何使用 sort.SliceStable() 對結(jié)構(gòu)體數(shù)組的某個字段進行穩(wěn)定排序,感興趣的可以了解一下
    2023-06-06
  • Golang中Gin框架中如何定義路由詳解

    Golang中Gin框架中如何定義路由詳解

    Gin是一個用Go語言編寫的Web框架,具有高性能和易于使用的特點,本文將結(jié)合實際案例,詳細(xì)介紹Gin框架的路由用法,有需要的小伙伴可以參考下
    2024-10-10
  • Go 微服務(wù)開發(fā)框架DMicro設(shè)計思路詳解

    Go 微服務(wù)開發(fā)框架DMicro設(shè)計思路詳解

    這篇文章主要為大家介紹了Go 微服務(wù)開發(fā)框架DMicro設(shè)計思路詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪
    2022-10-10
  • 詳解如何使用Golang擴展Envoy

    詳解如何使用Golang擴展Envoy

    這篇文章主要為大家介紹了詳解如何使用Golang擴展Envoy實現(xiàn)示例詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪
    2023-06-06
  • golang語言實現(xiàn)的文件上傳與文件下載功能示例

    golang語言實現(xiàn)的文件上傳與文件下載功能示例

    這篇文章主要介紹了golang語言實現(xiàn)的文件上傳與文件下載功能,結(jié)合實例形式分析了Go語言實現(xiàn)的文件傳輸相關(guān)操作技巧,需要的朋友可以參考下
    2020-02-02
  • Go編寫定時器與定時任務(wù)詳解(附第三方庫gocron用法)

    Go編寫定時器與定時任務(wù)詳解(附第三方庫gocron用法)

    當(dāng)需要每天執(zhí)行定時任務(wù)的時候就需要定時器來處理了,周期任務(wù),倒計時任務(wù),定點任務(wù)等,下面這篇文章主要給大家介紹了關(guān)于Go編寫定時器與定時任務(wù)的相關(guān)資料,文中通過實例代碼介紹的非常詳細(xì),需要的朋友可以參考下
    2022-07-07
  • K8s部署發(fā)布Golang應(yīng)用程序的實現(xiàn)方法

    K8s部署發(fā)布Golang應(yīng)用程序的實現(xiàn)方法

    本文主要介紹了K8s部署發(fā)布Golang應(yīng)用程序的實現(xiàn)方法，文中通過示例代碼介紹的非常詳細(xì)，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧
    2021-07-07
  • 詳解golang中的閉包與defer

    詳解golang中的閉包與defer

    閉包一個函數(shù)與其相關(guān)的引用環(huán)境組合的一個實體，其實可以理解為面向?qū)ο笾蓄愔械膶傩耘c方法，這篇文章主要介紹了golang的閉包與defer,需要的朋友可以參考下
    2022-09-09
  • Go中的?=?和?:=?區(qū)別小結(jié)

    Go中的?=?和?:=?區(qū)別小結(jié)

    在Go語言編程中,"="用于給已聲明的變量賦值,而":="同時聲明并初始化變量,只能在函數(shù)內(nèi)使用,理解這兩者的不同,有助于編寫更清晰的代碼,下面就來介紹一下
    2024-10-10
  • golang中使用mongo的方法介紹

    golang中使用mongo的方法介紹

    這篇文章主要給大家介紹了關(guān)于golang中使用mongo的相關(guān)資料，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧
    2018-08-08

最新評論