Golang gin框架使用swagger生成接囗文档

原创

已于 2023-01-11 16:32:15 修改 · 6.9k 阅读

收录于

当前文章被以下社区和专栏收录：

于 2022-04-16 06:00:00 首次发布

本文档详细介绍了如何在Go语言中使用Gin框架和Swag库来创建RESTful API，并通过注解生成Swagger UI，包括安装、编写注解、添加路由、生成文档、验证Token以及上传文件等功能，帮助开发者快速构建带有完整接口文档的Go应用。

0、开发环境

操作系统：Win10

Golang版本：1.15

1、安装swag

go get github.com/swaggo/swag/cmd/swag

此时会在环境变量 GOBIN目录中生成swag.exe，如下图所示

验证是否安装成功

F:\Golang\TalentChain\talentchain>swag -v
swag version v1.8.1

若没有生成，则可以使用以下命令：

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

2、安装依赖包

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles

3、编写注解及添加访问路由

（1）导入包

package main

import (
	//.....省略许多包
	_ "talentchain/docs" //talentchain是工程的module名称，改成自己工程的module名
)

注：必须导入docs，否则将报错： Failed to load API definition. 如下图所示：

（2）编写注解

注：注解详情可参见官网文档 Swagger Documentation

go-swapper注解规范说明

// @Summary 摘要

// @Description 描述

// @Description 接口的详细描述

// @Id 全局标识符

// @Version 接口版本号

// @Tags 接口分组，相当于归类

// @Accept json 浏览器可处理数据类型

// @Produce json 设置返回数据的类型和编码

// @Param 参数格式从左到右：参数名、入参类型、数据类型、是否必填和注释例：id query int true "ID"

// @Success 响应成功从左到右：状态码、参数类型、数据类型和注释例：200 {string} string "success"

// @Failure