【山东大学软件学院 21 级项目实训】在Gin框架下引入Swaggo生成API文档

前言

在现代 Web 开发中，API 文档对于开发者之间的协作至关重要。Swaggo 是一个用于自动生成 API 文档的工具，它通过注释的方式生成符合 OpenAPI 规范的文档。本文将介绍如何在 Gin 框架下引入 Swaggo 并生成 API 文档。

环境准备

在开始之前，请确保你已经安装了以下工具：

• Go 编程语言 (版本 1.16 及以上)
• Gin Web 框架
• Swaggo 工具

步骤一：创建一个新的Gin项目

首先，创建一个新的 Go 项目并初始化模块：

mkdir gin-swaggo-demo
cd gin-swaggo-demo
go mod init gin-swaggo-demo

然后，安装 Gin 框架：

go get -u github.com/gin-gonic/gin

步骤二：安装Swaggo工具

接下来，安装 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

步骤三：编写Gin代码并添加注释

创建一个简单的 Gin 服务器，并在代码中添加 Swaggo 所需的注释。创建一个 main.go 文件，内容如下：

package main

import (
    "github.com/gin-gonic/gin"
    _ "gin-swaggo-demo/docs" // 注意这里需要引入生成的docs包
    ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
)

// @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(":8080")
}

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

步骤四：生成Swagger文档

在项目根目录下运行以下命令以生成 Swagger 文档：

swag init

这将生成一个 docs 目录，里面包含了 Swagger 文档文件。

步骤五：运行服务器并访问Swagger UI

最后，运行你的 Gin 服务器：

go run main.go

打开浏览器并访问 http://localhost:8080/swagger/index.html，你将看到自动生成的 Swagger UI 界面，其中展示了你的 API 文档。