Golang使用Swag搭建api文档

1. 简介

Gin是Golang目前最为常用的Web框架之一。

公司项目验收需要API接口设计说明书（Golang后端服务基于Gin框架编写），编写任务自然就落到了我们研发人员身上。

项目经理提供了文档模板，让我们参考模板来手动编写，要求两天内完成，时间紧任务重。

看了下文档中API接口设计内容，很简单，但是接口数量太多还需要调整文档格式，手动编写两天肯定搞不定。

发现API接口设计内容和swagger文档格式很相近，那能不能使用工具生成swagger文档后再转换为word格式呢？

和项目经理沟通了我的想法，项目经理回答说，内容丰富、格式统一就行，不要求完全参考模板中的格式来。

既然这样，那就开干吧！

2. 生成`swagger.json`文档

本章节仅为演示操作步骤，编写得很简洁。如果需要进一步的了解请查阅【[4. 参考资料](#4. 参考资料)】章节

2.1. 安装`swag`

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

2.2. 新建示例项目

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

2.3. 新建`main.go`文件并输入示例代码

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")
}