gin-swagger自动生成接口文档 | 青训营笔记

SDS_jbxxanjdy
707 阅读5分钟

这是我参与「第五届青训营」笔记创作活动的第 5 天

Swagger简介

Swagger定义

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger的优势

  • 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
  • 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

Swagger的下载和安装

使用如下命令下载swag：

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/http-swagger
go get -u github.com/alecthomas/template

前两个命令分别安装swag和http-swagger;第三个命令是安装模板，这是Go的text/template包的分支。

注意:go get命令是下载命令，不是安装命令;我们还需要使用 go install 命令安装Swagger。

命令如下:

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

Swagger的使用

通用API注释

我们首先通过注释我们的main方法来添加整个项目的一般描述。如下所示

// @title 青训营笔记
// @version 1.0
// @description 学习swagger技术
// @host 127.0.0.1:8080
// @BasePath /
func main() {
   r := gin.Default()
   r.GET("/", UserList)
   r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
   r.Run(":8080")
}

其中：

  • titile: 文档标题
  • version: 版本
  • description,termsOfService,contact ... 这些都是一些声明，可不写。
  • host,BasePath: 如果你想直接swagger调试API，这两项需要填写正确。前者为服务文档的端口，ip。后者为基础路径，像我这里就是“/”。

API操作

接下来，我们需要在每个路由处理函数上加上注释，如：

type Response struct {
   Code int    `json:"code"`
   Msg  string `json:"msg"`
   Data any    `json:"data"`
}

// UserList 用户列表
// @Summary 用户列表
// @Description 添加用户列表
// @Tags 用户管理
// @Accept  json
// @Produce  json
// @Param code header int true "编码"
// @Param msg body string true "信息" default(admin)
// @Param data formData any true "数据"
// @Router /api/users [get]
// @Success 200 {object} Response
func UserList(c *gin.Context) {
   c.JSON(http.StatusOK, Response{0, "LiuBing", 2.10})
}

这些注释会出现在API文档对应的位置，这里我们主要详细说说下面参数：

  • Tags:Tags 是用来给API分组的。

  • Accept:接收的参数类型，支持表单(mpfd) , JSON(json)等，更多如下表。

  • Produce:返回的数据结构，一般都是json, 其他支持如下表：

image.png

参数，从前往后分别是：

@Param msg body string true "信息" default(admin)

@Param 1.参数名 2.参数类型 3.参数数据类型 4.是否必须 5.参数描述 6.其他属性

1.参数名

参数名就是我们解释参数的名字。

2.参数类型

参数类型主要有5种：path、query、formData、body、header

3.参数数据类型

数据类型主要支持一下几种：

string (string)

integer (int, uint, uint32, uint64)

number (float32)

boolean (bool)

注意，如果你是上传文件可以使用file, 但参数类型一定是formData,。

4.是否是必须

表明该参数是否是必须需要的，必须的在文档中会黑体标出，测试时必须填写。

5.参数描述

就是参数的一些说明

6.其他属性

除了上面这些属性外，我们还可以为该参数填写一些额外的属性，如枚举，默认值，值范围等。如下：

  • 枚举
// @Param enumstring query string false "string enums" Enums(A, B, C)

// @Param enumint query int false "int enums" Enums(1, 2, 3)

// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)
  • 值添加范围
// @Param string query string false "string valid" minlength(5) maxlength(10)

// @Param int query int false "int valid" mininum(1) maxinum(10)
  • 设置默认值
// @Param default query string false "string default" default(A)

而且这些参数是可以组合使用的，如：

// @Param enumstring query string false "string enums" Enums(A, B, C) default(A)
  • Success 指定成功响应的数据。格式为：
// @Success 1.HTTP响应码 {2.响应参数类型} 3.响应数据类型 4.其他描述

1.HTTP响应码

也就是200，400，500那些。

2.响应参数类型

3.响应数据类型

返回的数据类型，可以是自定义类型，可以是json。

  • 自定义类型 在平常的使用中，我都会返回一些指定的模型序列化JSON的数据，这时，就可以这么写：
// @Success 200 {object} main.File

其中，模型直接用包名.模型即可。你会说，假如我返回模型数组怎么办？这时你可以这么写：

// @Success 200 {anrry} main.File

将如你只是返回其他的数据格式可如下写：

// @Success 200 {string} string ""
  • Router 指定路由与HTTP方法。格式为：
// @Router /path/to/handle [HTTP方法]

生成swagger.json

使用swag init命令生成swagger文档

引入gin-swagger渲染文档数据

import (
   "github.com/gin-gonic/gin"
   swaggerFiles "github.com/swaggo/files"
   gs "github.com/swaggo/gin-swagger"
   "net/http"
   _ "swagger_demo/swag_doc/docs" // 千万不要忘了导入把你上一步生成的docs
)

把你的项目程序运行起来，打开浏览器访问http://localhost:8080/swagger/index.html 就能看到Swagger 2.0 Api文档了。

image.png

avatar
文章
阅读
粉丝