使用 Swagger 在 Golang 中进行 API 文档生成

Swagger 是一款强大的 API 文档生成工具,可以帮助开发者轻松创建、管理和展示 RESTful API 文档。在本文中,我们将介绍如何在 Golang 项目中使用 Swagger 来生成 API 文档。

官网地址 : gin-swagger

前提条件

  • Golang 开发环境(推荐使用 Go 1.16 或更高版本)
  • Go Modules 管理工具
  • 已安装的 Git 工具

第一步:安装 Swagger 工具

在开始之前,我们需要安装 Swagger 工具。你可以使用以下命令来安装 Swagger:

go 复制代码
go install github.com/swaggo/swag/cmd/swag@latest

安装完成后,可以通过运行以下命令来验证安装是否成功:

go 复制代码
swag --v

第二步:安装 Swaggo 依赖

Swaggo 是一个用于 Golang 的 Swagger 文档生成器。我们需要在项目中安装 Swaggo 依赖:

go 复制代码
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 代码

接下来,我们编写一个简单的 API 示例。在项目根目录下创建一个 main.go 文件,并添加以下内容:

go 复制代码
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",
    })
}

第四步:生成 Swagger 文档

在编写好 API 代码后,我们可以使用 Swaggo 生成 Swagger 文档。在项目根目录下运行以下命令:

go 复制代码
swag init

运行此命令后,会在项目根目录下生成 docs 文件夹,其中包含生成的 Swagger 文档。

第五步:运行项目并访问 Swagger UI

最后,我们运行项目,并访问 Swagger UI。运行以下命令启动项目:

bash 复制代码
go run main.go

在浏览器中访问 http://localhost:8080/swagger/index.html,即可看到生成的 Swagger UI 页面,其中包含了我们编写的 API 文档。

相关推荐
我不会起名字3228 小时前
仅 Web 主动 ping:30 秒读超时与各平台保活
前端·后端·websocket·go·即时通讯·im·故障排查
星星在线9 小时前
Go + gRPC 插件式服务框架 —— 技术实现与分析
go
Java码农也是农10 小时前
一篇文章讲清 Go 并发:goroutine、channel、select 与取消
go·并发编程·context·channel·goroutine
afumu1 天前
Go 写一个只监听 127.0.0.1 的控制服务:鉴权、白名单、危险命令拦截
后端·安全·go
我不会起名字3221 天前
未接入最终读上限的参数:`websocketMaxMsgLen` 与 12.5 倍差距
后端·websocket·go·即时通讯·im·故障排查
王中阳Go1 天前
100 件货卖出 116 件,库存停在 -16
后端·mysql·go
我不会起名字3222 天前
req.Seqs[len-1]:空切片防御缺口与 RPC 二次校验
后端·mongodb·go·即时通讯·im·故障排查
我不会起名字3223 天前
会话缓存失效排查:区分 Redis 失效与节点广播
redis·后端·go·即时通讯·im·故障排查
大然Ryan4 天前
我用 Go 和 AI 做了一个 macOS 磁盘清理工具:Vole(开源)
go
我不会起名字3224 天前
seq 空洞排查:Mongo 的 51 只是预留上界,Redis CURR 才是已消耗边界
redis·后端·mongodb·go·即时通讯·im·故障排查