使用GO--Swagger生成文档

概述 

在前后端分离的项目中，后端配置swagger可以很好的帮助前端人员了解后端接口参数和数据传输。go-swagger 是一个功能全面且高性能的Go语言实现工具包，用于处理Swagger 2.0（即OpenAPI 2.0）规范。它提供了丰富的工具集，帮助开发者在Go环境中解析、生成、验证和操作API描述文件。（OpenAPI 2.0 ：用于生成、描述、调用和可视化RESTful Web服务。它允许你使用YAML或JSON格式定义API接口，包括路径、参数、请求方法、响应类型等信息。）

特点

• 定制化支持: 具备强大的自定义能力，通过供应商扩展和可自定义模板，满足不同需求。

• 代码生成: 专注于产出语义正确、运行高效的Go代码，兼容golint, go vet等工具。

基本使用

安装

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

安装后，通过：swag -v  测试是否安装成功

 使用步骤

以gin框架为例：

1. 需要用到gin-swagger库：

go get -u github.com/swaggo/gin-swagger //gin-swagger中间件
go get -u github.com/swaggo/files //swagger嵌入文件

gin-swagger使用步骤：

• 按照swagger要求给接口代码添加声明式注释，具体参照声明式注释格式。
• 使用swag工具扫描代码自动生成API接口文档数据
• 使用gin-swagger渲染在线接口文档页面

 2. 添加注释

项目添加注释：（在main函数下添加下面的注释）

// @可以修改的swagger文档的标题

// @version 版本

// @description  这里是swagger中整个项目的描述

// @termsOfService https://www.swagger.io/terms/

// @contact.name  维护者名字

// @contact.url 维护者联系网址

// @contact.email 维护者邮件

// @license.name Apache 2.0

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

// @host 127.0.0.1:8080

// @BasePath /api/v1

title：文档标题
version：版本
description，termsOfService，contact.name contact.url，contact.email都是一些声明，可不写。
license：是必须的
host，BasePath：如果你想直接swagger调试API，这两项需要填写正确。前者为服务文档的端口，ip。后者为基础路径，像我们这里就是"/api/v1"。
在原文档中还有securityDefinitions.basic , securityDefinitions.apikey等，这些都是
用来做认证的。其他的可以看官方文档

函数接口添加注释：（在代码中处理请求的接口函数(通常位于controller层)，按如下方式注释。）

// @Summary 测试ping

    // @Description ping

    // @Tags 测试

    // @Accept json

    // @Success 200 {string} string "{"msg": "pong"}"

    // @Failure 400 {string} string "{"msg": "nonono"}"

    // @Router /ping [get]

 3. 下面直接使用命令，初始化我们的swagger文档：

swag init 

生成 docs文档：文档结构如下：

docs

        docs.go

        swagger.json

        swagger.yaml

注意：我们初始化的时候，一定是当前目录中有main.go的文件 ，不是有main函数的文件

4. 导入刚才的docs包（注意是匿名导入）

下面是所有方法的基本示例：

package main

import (
	"github.com/gin-gonic/gin"

    swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
    _ "component/swagger/docs"

)

// @可以修改的swagger文档的标题
// @version 版本(默认1.0)
// @description  这里是swagger中整个项目的描述
// @termsOfService https://www.swagger.io/terms/
 
// @contact.name  维护者名字
// @contact.url http://www.swagger.io/support
// @contact.email 维护者邮件
 
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
 
// @host 127.0.0.1:8080
// @BasePath /api/v1
func main() {
    r := gin.Default()
    //在代码中处理请求的接口函数(通常位于controller层)，按如下方式注释。

    //注册swagger api相关路由
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // 设置路由组/api/v1
    g := r.Group("/api/v1")
    {
        g.GET("/ping",PingHandler)
        
        g.POST("/login",LoginHandler)
        
    }

    r.Run("127.0.0.1:8080")
}

// 模型（model）
type User struct{
    Username string    `json:"username" example:"张三"`
    Password string    `json:"password" example:"123456"`
}

// 响应参数模型（model）
type ResponseParam struct {
    Code int `json:"code"`
    Message string `json:"message"`
    Data *User  `json:"data"` 
}

// 接收参数模型（model）
type RequestParam struct {
    Username string    `json:"username" example:"李四"`
    Password string    `json:"password" example:"123456"`
}

// 接收参数模型2（model）
type RequestParam2 struct {
    Username string    `json:"username" example:"李四"`
    Password string    `json:"password" example:"123456"`
    UpdateUsername string `json:"updateusername" example:"张三"`
    UpdatePassword string `json:"updatepassword" example:"789100"`
}

// @Summary 测试ping
    // @Description ping
    // @Tags 测试1
    // @Accept application/json
    // @Success 200 {string} string "{"msg": "pong"}"
    // @Failure 400 {string} string "{"msg": "nonono"}"
    // @Router /ping [get]
func PingHandler(ctx *gin.Context){
    ctx.JSON(200,gin.H{
        "code": 1000,
       "msg": "pong",
    })
}

    // @Summary 测试login
    // @Description login
    // @Tags 测试2
    // @Accept application/json
    // @Produce application/json
    // @Param Object body RequestParam true "用户信息"
    // @Success 200 {object} ResponseParam
    // @Failure 400 {string} string "{"msg": "failed"}"
    // @Router /login [post]
func LoginHandler(c *gin.Context){
    user := new(User)
    err := c.ShouldBindJSON(user)
    if err != nil{
        c.JSON(200,gin.H{
            "code": 5000,
            "msg": user,
        })
    }
    c.JSON(200,gin.H{
        "code": 2000,
        "msg": user,
    })
}

    // @Summary 删除用户
    // @Description deleteuser
    // @Tags 测试3
    // @Accept application/json
    // @Produce application/json
    // @Param id path int true "用户id"
    // Success 200 {string} string "{"msg": "该id="{{id}}"用户已经被注销"}"
    // Failure 400 {string} string "{"msg": "该id不存在"}"
    // @Router /user [delete]
func DeleteUser(c *gin.Context){
    // 传来待删除用户的id(路径参数)
    id := c.Param("id")
    ok := (id == "1")
    if ok {
        c.JSON(200,gin.H{
            "code": 5000,
            "msg": ("该id="+id+"用户不存在"),
        })
    }
    c.JSON(200,gin.H{
        "code": 2000,
        "msg": ("该id="+id+"用户已经被注销"),
    })

}

    //@Summary 更新用户信息
    // @Description update
    // @Tags 测试4
    // @Accept application/json
    // @Produce application/json
    // @Param Object body RequestParam2 true "用户更新后信息"
    // @Success 200 {object} ResponseParam
    // @Failure 400 {string} string "{"msg": "failed"}"
    // @Router /update [put]
func UpdateUser(c *gin.Context){

}

注意：在每次更新接口和注释信息后，要重新进行swag init初始化文档

服务启动后，访问：（每个人的端口可能不一样，我这里是8080）Swagger UIhttp://127.0.0.1:8080/swagger/index.html#/

 在文档中还可以直接进行调试，进行接收请求和响应。

在编写声明式注释时，需要知道以下东西

1. 常见的声明式注释格式及选项（以 Swagger 为例）

   • @Summary：
     • 格式：@Summary <简短描述>
     • 用途：用于提供一个简洁的、对 API 接口功能的总结性描述。这个描述应该能够让使用者快速了解接口主要是做什么的。例如，@Summary 获取用户信息 或者 @Summary 删除指定订单。
   • @Description：
     • 格式：@Description <详细描述>
     • 用途：提供比 @Summary 更详细的关于接口的信息，包括接口的业务逻辑、操作细节、特殊情况等内容。比如，@Description 根据用户ID从数据库中查询用户的详细信息，包括姓名、年龄、联系方式等。
   • @Tags：
     • 格式：@Tags <标签列表>，其中标签列表可以是一个或多个用逗号隔开的标签。
     • 用途：用于对接口进行分类，方便在 API 文档中通过标签来组织和查找接口。例如，@Tags 用户管理,权限管理，这样可以将与用户管理相关的接口和权限管理相关的接口通过不同的标签区分开来，便于文档管理和查看。
   • @Accept：
     • 格式：@Accept <媒体类型列表>，媒体类型之间可以用逗号隔开。
     • 用途：指定接口能够接受的请求内容类型。如 @Accept application/json,text/plain，表明该接口可以接受 JSON 格式和纯文本格式的请求内容。
   • @Produce：
     • 格式：@Produce <媒体类型列表>
     • 用途：用于说明接口会产生（返回）的内容类型。例如，@Produce application/json，意味着这个接口返回的数据格式是 JSON。
   • @Param：
     • 格式：@Param <参数名> <参数位置> <参数类型> <是否必填> <参数描述>
     • 参数位置常见类型：
       • path：表示参数是在路径中传递的，如 /users/{user_id} 中的 user_id。
       • query：参数是在查询字符串中，例如 /products?category=electronics 中的 category。
       • body：参数在请求体中，一般用于传递较为复杂的数据结构，像创建用户时，用户信息以 JSON 等格式放在请求体中。
     • 用途：用于详细描述接口接受的参数，包括参数的名称、位置、类型、是否必填以及参数的具体含义等信息。例如，@Param user_id path int true "用户ID，用于唯一标识用户"。
   • @Success：
     • 格式：@Success <状态码> <返回类型> <返回描述>
     • 用途：描述接口成功响应时的情况，包括返回的状态码、数据类型以及返回内容的简单描述。例如，@Success 200 {object} UserInfo "成功返回用户的详细信息"，这里表示接口成功时返回状态码为 200，数据类型是一个对象（{object}，具体类型可能是自定义的结构体等，这里假设是 UserInfo），并且说明了返回的是用户详细信息。
   • @Failure：
     • 格式：@Failure <状态码> <返回类型> <返回描述>
     • 用途：和 @Success 相对应，用于描述接口失败时的情况，包括可能出现的错误状态码、返回的数据类型（如果有返回内容的话）以及错误内容的简单描述。例如，@Failure 404 {string} "用户不存在"，说明当出现 404 状态码时，返回的数据类型可能是一个字符串，并且内容是提示用户不存在。
   • @Router：
     • 格式：@Router <路径> [<方法>]
     • 用途：用于指定接口对应的路由路径和请求方法。例如，@Router /users/{user_id} [GET]，表明这个接口对应的路径是 /users/{user_id}，请求方法是 GET，用于获取特定用户的信息。

 然后，需要注意的是：为什么你的swagger中，有些函数可以出现，有些没有出现

一定要注意参数格式！

一定要注意参数格式！

一定要注意参数格式！