Golang使用Swag搭建api文檔的全過程

更新時間：2024年02月28日 10:40:33 作者：蜀中攻城獅

Gin是Golang目前最為常用的Web框架之一,公司項目驗收需要API接口設計說明書（Golang后端服務基于Gin框架編寫）,所以本文給大家介紹了Golang使用Swag搭建api文檔的全過程,需要的朋友可以參考下

1. 簡介

Gin是Golang目前最為常用的Web框架之一。
公司項目驗收需要API接口設計說明書（Golang后端服務基于Gin框架編寫），編寫任務自然就落到了我們研發(fā)人員身上。
項目經(jīng)理提供了文檔模板，讓我們參考模板來手動編寫，要求兩天內完成，時間緊任務重。

看了下文檔中API接口設計內容，很簡單，但是接口數(shù)量太多還需要調整文檔格式，手動編寫兩天肯定搞不定。
發(fā)現(xiàn)API接口設計內容和swagger文檔格式很相近，那能不能使用工具生成swagger文檔后再轉換為word格式呢？

和項目經(jīng)理溝通了我的想法，項目經(jīng)理回答說，內容豐富、格式統(tǒng)一就行，不要求完全參考模板中的格式來。
既然這樣，那就開干吧！

2. 生成swagger.json文檔

本章節(jié)僅為演示操作步驟，編寫得很簡潔。

2.1. 安裝swag

首先需要安裝swag命令行工具：go install github.com/swaggo/swag/cmd/swag@latest。

2.2. 新建示例項目

比如新建swagdoc項目：go mod init swagedoc。

2.3. 新建main.go文件并輸入示例代碼

package main

import (
    "net/http"

    "swagdoc/docs"

    "github.com/gin-gonic/gin"
    swaggerfiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

// @BasePath /api/v1

// PingExample godoc
// @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() {
    r := gin.Default()
    docs.SwaggerInfo.BasePath = "/api/v1"
    v1 := r.Group("/api/v1")
    {
        eg := v1.Group("/example")
        {
            eg.GET("/helloworld", Helloworld)
        }
    }
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
    r.Run(":8080")
}