快捷導(dǎo)航

Golang中使用Swagger生成API文檔的流程步驟

更新時(shí)間：2024年07月25日 09:41:20 作者：小小的木頭人

Swagger 是一款強(qiáng)大的 API 文檔生成工具,可以幫助開發(fā)者輕松創(chuàng)建、管理和展示 RESTful API 文檔,在本文中,我們將介紹如何在 Golang 項(xiàng)目中使用 Swagger 來生成 API 文檔,文中有相關(guān)的代碼示例供大家參考,需要的朋友可以參考下

前提條件

Golang 開發(fā)環(huán)境（推薦使用 Go 1.16 或更高版本）
Go Modules 管理工具
已安裝的 Git 工具

第一步：安裝 Swagger 工具

在開始之前，我們需要安裝 Swagger 工具。你可以使用以下命令來安裝 Swagger：

go install github.com/swaggo/swag/cmd/swag@latest

安裝完成后，可以通過運(yùn)行以下命令來驗(yàn)證安裝是否成功：

swag --v

第二步：安裝 Swaggo 依賴

Swaggo 是一個(gè)用于 Golang 的 Swagger 文檔生成器。我們需要在項(xiàng)目中安裝 Swaggo 依賴：

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

第三步：編寫 API 代碼

接下來，我們編寫一個(gè)簡單的 API 示例。在項(xiàng)目根目錄下創(chuàng)建一個(gè) main.go 文件，并添加以下內(nèi)容：

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    _ "go-swagger-example/docs"
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /api/v1

func main() {
    r := gin.Default()

    // Simple group: v1
    v1 := r.Group("/api/v1")
    {
        v1.GET("/hello", helloHandler)
    }

    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run()
}

// helloHandler godoc
// @Summary Show a hello message
// @Description get string message
// @Tags example
// @Accept  json
// @Produce  json
// @Success 200 {string} string "ok"
// @Router /hello [get]
func helloHandler(c *gin.Context) {
    c.JSON(200, gin.H{
        "message": "hello world",
    })
}