go——Swagger使用

一. 为什么后端需要配置Swagger

        在前后端分离的项目中，后端配置swagger可以很好的帮助前端人员了解后端接口参数和数据传输。

        Swagger是一个用于设计，构建和文档化API的开源框架。在Go语言中，Swagger可以帮助后端开发人员快速创建和定义RESTful API，并提供自动生成接口文档的功能，这些文档包含了API的详细信息以及如何使用他们的说明。

RESTful API：

        RESTful是一个网络应用程序的设计风格，基于HTTP协议。使用XML或JSON格式定义统一标准接口。强调资源，统一接口，URL和无状态的设计风格。

        总的来说，RESTful就是一个资源定位，资源操作的风格。不是标准也不是协议，只是一种风格。

  • 资源：互联网所有的事务都可以抽象为资源
  • 资源操作：分为POST，DELETE，PUT，GET四种方法，使用不同的方法对资源进行操作(增，删，改，查)

传统风格与RESTful风格对比：

  • 传统风格：通过不同的参数实现不同的效果，方法单一。

http://127.0.0.1/item/queryItem.action?id=1 （查询,GET） http://127.0.0.1/item/saveItem.action （新增,POST） http://127.0.0.1/item/updateItem.action （更新,POST） http://127.0.0.1/item/deleteItem.action?id=1 （删除,GET或POST）

  • RESTful方式操作资源：通过不同的请求方式来实现不同的效果。

        如下：请求资源地址相同，但是功能不同。

http://127.0.0.1/item/1 （查询,GET）

http://127.0.0.1/item （新增,POST）

http://127.0.0.1/item （更新,PUT）

http://127.0.0.1/item/1 （删除,DELETE）

        现在的网络上基本上全是RESTful风格。

二. 基本使用

        2.1 安装

        安装最新swagger库：

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

        测试是否安装成功：

        2.2 使用步骤

         以Gin框架为例，需要用到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.3 添加注释

        在程序入口main函数上以注释的方式写下项目相关介绍信息。

// @title Swagger Example API
// @version 1.0
// @description this is a sample server celler server
// @termsOfService https://www.swagger.io/terms/// @contact.name 氷
// @contact.url http://www.swagger.io/support
// @contact.email abc.xyz@qq.com// @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 测试sayHello
// @Description 向你说hello
// @Tags 测试
// @Accept json
// @Param name query string true "人名"
// @Success 200 {string} string "{"msg": "hello wy"}"
// @Failure 400 {string} string "{"msg": "who are you"}"
// @Router /hello [get]

通用API信息：

注释描述
AcceptAccept字段仅适用于带有request body的请求，例如POST、PUT和PATCH。只有使用这些请求方法的接口才需要定义接收的 MIME 类型列表。
Produce定义接口返回的 MIME 类型列表。

MIME类型

别名MIME Type
json    application/json
xml     text/xml
plain    text/plain
html     text/html
mpfd    multipart/form-data
x-www-form-urlencodedapplication/x-www-form-urlencoded
json-apiapplication/vnd.api+json
json-streamapplication/x-json-stream
octet-stream application/octet-stream
png image/png
jpeg image/jpeg
gif image/gif

API操作：

  • @Summary    接口功能的简要概述。
  • @Description    接口的详细说明。
  • @Tags    接口的标签列表，可以有多个标签，每个标签用英文的逗号分隔。这样接口会按照标签进行分类。
  • @Param    接口接收的数据，参数用空格分隔。参数分别是：“参数名” “参数类型” “数据类型” “是否必须” “参数的描述” “其它属性”。
  • @Success    接口的成功响应语法格式：“响应的状态码” “响应参数类型” “响应数据类型” “描述信息”。
  • @Failure    接口的故障响应语法格式：“响应的状态码” “响应参数类型” “响应数据类型” “描述信息”。
  • @Response    与@Success和@Failure的作用相同。
  • @Router    接口的路由定义，用空格隔开路径和请求方法。 path [httpMethod]
  • @Security    定义接口的安全性

Param

参数类型

  • query：该类型参数直接拼接在URL中。URL中后面的参数
  • path：该类型参数一般组合在URL中。如：/api/v1/:id
  • header：
  • body
  • formData：该类型参数一般是POST，PUT方法所用。

数据类型

  • string (string)
  • integer (int, uint, uint32, uint64)
  • number (float32)
  • boolean (bool)
  • object (struct)

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

其它属性：

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

枚举
// @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)

 Success/Failure

响应状态码：也就是200，400，500这些

响应参数类型：整个数据类型。string表示字符串，object表示自定义类型，anrry表示数组

响应数据类型：具体当个数据的类型。

描述信息：其它说明。

例如：

表示响应状态码200 响应是参数字符串类型，数据也是字符串类型
// @Success 200 {string} string表示响应状态码200 响应是参数自定义类型，数据也是自定义类型为main包中的File类型
// @Success 200 {object} main.File表示响应状态码200 响应是参数数组类型，数据类型表示数组中单个元素类型为main包中的File类型
//@Success 200 {anrry} main.File表示响应状态码200 响应是参数字符串类型，数据类型字符串表示的是json类型// @Success 200 {string} json ""

Router 

        格式：

        不需要加基础路径。

//Router /path/to/handle [http方法]

        2.4 测试示例

自动生成swagger文档

package mainimport ("net/http""github.com/gin-gonic/gin"swaggerFiles "github.com/swaggo/files"ginSwagger "github.com/swaggo/gin-swagger"
)// @title Swagger Example API
// @version 1.0
// @description this is a sample server celler server
// @termsOfService https://www.swagger.io/terms/// @contact.name 氷
// @contact.url http://www.swagger.io/support
// @contact.email abc.xyz@qq.com// @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()//注册swagger api相关路由r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))v := r.Group("/api/v1"){v.GET("/hello", helloHandler)}r.Run()
}// helloHandler
// @Summary 测试sayHello
// @Description 向你说hello
// @Tags 测试
// @Accept json
// @Param name query string true "人名"
// @Success 200 {string} string "{"msg": "hello wy"}"
// @Failure 400 {string} string "{"msg": "who are you"}"
// @Router /hello [get]
func helloHandler(c *gin.Context) {name := c.Query("name")if name == "" {c.JSON(http.StatusBadRequest, gin.H{"msg": "who are you"})return}c.JSON(http.StatusOK, gin.H{"msg": "hello" + name})
}

        在main.go目录下执行swag init就可以当前目录下自动生成文档： 

        然后我们在main.go中导入自动生成的docs包，运行： 

package mainimport ("net/http""github.com/gin-gonic/gin"swaggerFiles "github.com/swaggo/files"ginSwagger "github.com/swaggo/gin-swagger"_ "sample-app/swagger/docs"
)//...

        浏览器打开http://127.0.0.1:8080/swagger/index.html，我们可以看到对于接口文档。

         介绍：

         点击Try it out就可以进行测试：

        2.5 多个tags

package mainimport ("net/http""github.com/gin-gonic/gin"swaggerFiles "github.com/swaggo/files"ginSwagger "github.com/swaggo/gin-swagger"_ "sample-app/swagger/docs"
)// @title Swagger Example API
// @version 1.0
// @description this is a sample server celler server
// @termsOfService https://www.swagger.io/terms/// @contact.name 氷
// @contact.url http://www.swagger.io/support
// @contact.email abc.xyz@qq.com// @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()//注册swagger api相关路由r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))v := r.Group("/api/v1"){v.GET("/hello", helloHandler)v.GET("/hello1", helloHandler1)v.GET("/load", loadHandler)}r.Run()
}// @Summary 测试sayHello
// @Description 向你说hello
// @Tags 测试
// @Accept json
// @Param name query string true "人名"
// @Success 200 {string} string "{"msg": "hello wy"}"
// @Failure 400 {string} string "{"msg": "who are you"}"
// @Router /hello [get]
func helloHandler(c *gin.Context) {name := c.Query("name")if name == "" {c.JSON(http.StatusBadRequest, gin.H{"msg": "who are you"})return}c.JSON(http.StatusOK, gin.H{"msg": "hello" + name})
}// @Summary 测试sayHello other
// @Description 向你说hello
// @Tags 测试
// @Accept json
// @Param name query string true "人名"
// @Success 200 {string} string "{"msg": "hello wy"}"
// @Failure 400 {string} string "{"msg": "who are you"}"
// @Router /hello1 [get]
func helloHandler1(c *gin.Context) {name := c.Query("name")if name == "" {c.JSON(http.StatusBadRequest, gin.H{"msg": "who are you"})return}c.JSON(http.StatusOK, gin.H{"msg": "hello" + name})
}// @Summary 加载账号密码
// @Description 加载账号密码
// @Tags 加载
// @Accept json
// @Param id query string true "账号"
// @Param passwd query string true "密码"
// @Success 200 {string} json "{"msg": "id:asd passwd:2123"}"
// @Failure 400 {string} json "{"msg": "账号或密码错误"}"
// @Router /load [get]
func loadHandler(c *gin.Context) {name := c.Query("id")passwd := c.Query("passwd")if name == "" || passwd == "" {c.JSON(http.StatusBadRequest, gin.H{"msg": "账号或密码错误"})return}c.JSON(http.StatusOK, gin.H{"msg": "id:" + name + " passwd:" + passwd})
}

         重新在命令行输入swag init。生成swag文档，运行main.go。访问为：http://127.0.0.1:8080/swagger/index.html

三. 优化 

        swagger文档只是我们测试的时候需要，当我们产品上线后，接口文档是不应该给用户的，并且带有接口文档的包会大很多(swaggo是直接build到二进制中的)

        想处理这种情况，我们可以在编译的时候优化一下。比如利用build -tags来控制是否编译文档。

        go build -tags 是一个 Go 语言的命令行选项，用于在构建过程中启用或禁用特定的编译标签。这些标签通常用于控制代码的特定行为，例如启用或禁用某些功能、优化等

        比如：下面表示，tag1 和 tag2 是你想要启用的标签。你可以根据需要添加更多的标签，用空格分隔。

go build -tags "tag1 tag2"

         在你的 Go 代码中，你可以使用 // +build 注释来指定哪些文件应该在特定的标签下编译。

        在main.go声明swagHandler变量，并在该参数不为空时才加入路由。编译带docs标签的swagHandler才不会为空。才可以使用swagger接口文档。

        docs.go 

//go:build docs
// +build docspackage mainimport (_ "sample-app/swagger/docs"swaggerFiles "github.com/swaggo/files"ginSwagger "github.com/swaggo/gin-swagger"
)func init() {swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)
}

        main.go

package mainimport ("net/http""github.com/gin-gonic/gin"_ "sample-app/swagger/docs"
)var swagHandler gin.HandlerFunc// @title Swagger Example API
// @version 1.0
// @description this is a sample server celler server
// @termsOfService https://www.swagger.io/terms/// @contact.name 氷
// @contact.url http://www.swagger.io/support
// @contact.email abc.xyz@qq.com// @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()//不为空，才会加入swagger路由if swagHandler != nil {//注册swagger api相关路由r.GET("/swagger/*any", swagHandler)}v := r.Group("/api/v1"){v.GET("/hello", helloHandler)}r.Run()
}// @Summary 测试sayHello
// @Description 向你说hello
// @Tags 测试
// @Accept json
// @Param name query string true "人名"
// @Success 200 {string} string "{"msg": "hello wy"}"
// @Failure 400 {string} string "{"msg": "who are you"}"
// @Router /hello [get]
func helloHandler(c *gin.Context) {name := c.Query("name")if name == "" {c.JSON(http.StatusBadRequest, gin.H{"msg": "who are you"})return}c.JSON(http.StatusOK, gin.H{"msg": "hello" + name})
}

        带标签比不带标签编译出来的文件大小大很多。 

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/news/866355.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

君子签区块链+AI，驱动组织实现高效合同管理、精准风险控制

君子签区块链+AI，驱动组织实现高效合同管理、精准风险控制

在传统合同签署的过程中，企业、组织、机构都面临着合同签署与管理的诸多问题和挑战：合同种类繁多、数量庞大导致起草效率低下；管理流程繁琐、权限分散使得审批周期冗长且效率低下；合同签订版本难以精准复核，风险防控更…
阅读更多...
用Vue3和Plotly.js绘制交互式3D烛形图

用Vue3和Plotly.js绘制交互式3D烛形图

本文由ScriptEcho平台提供技术支持 项目地址：传送门 Plotly.js实现交互式K线图 应用场景 K线图广泛应用于金融领域，用于展示股票、外汇等金融产品的价格走势。它直观地呈现了开盘价、收盘价、最高价和最低价等信息，帮助投资者分析市场趋势…
阅读更多...
克隆gitee仓库，在vs2022创建文件夹开发项目操作步骤

克隆gitee仓库，在vs2022创建文件夹开发项目操作步骤

git网站 git知识大全 git教程：廖雪峰的官方网站 git菜鸟教程 gitee之创建项目步骤 同步源仓库 2. 克隆命令 3. 右击git Bash Here>粘贴命令行 4. 选中项目文件夹》创建本人文件夹（ZYY） 5. 打开vs2022》新建项目》选择Framework》下…
阅读更多...
第二届计算机、视觉与智能技术国际会议（ICCVIT 2024）

第二届计算机、视觉与智能技术国际会议（ICCVIT 2024）

随着科技的飞速发展，计算机、视觉与智能技术已成为推动现代社会进步的重要力量。为了汇聚全球顶尖专家学者，共同探讨这一领域的最新研究成果和前沿技术，第二届计算机、视觉与智能技术国际会议（ICCVIT 2024）将于2024年1…
阅读更多...
【Unity navmeshaggent 组件】

【Unity navmeshaggent 组件】

【Unity navmeshaggent 组件】 组件概述： NavMeshAgent是Unity AI系统中的一个组件，它允许游戏对象（通常是一个角色或AI）在导航网格（NavMesh）上自动寻路。 组件属性： Radius：导航…
阅读更多...
springboot课堂考勤系统-计算机毕业设计源码94408

springboot课堂考勤系统-计算机毕业设计源码94408

目 录 1 绪论 1.1 选题背景和意义 1.2国内外研究现状 1.3论文结构与章节安排 2 课堂考勤系统系统分析 2.1 可行性分析 2.1.1技术可行性分析 2.1.2 操作可行性分析 2.1.3 法律可行性分析 2.2 系统功能分析 2.2.1 功能性分析 2.3 系统用例分析 2.4 系统流程分析 2.…
阅读更多...
免费的鼠标连点器哪个好用？5款2024年最新鼠标连点器分享

免费的鼠标连点器哪个好用？5款2024年最新鼠标连点器分享

鼠标连点器是电脑网络游戏爱好者并不陌生的游戏辅助工具，他在FPS、RTS、moba等游戏种类中发挥着重要作用。可以帮助玩家的鼠标完成各种简单点击动作。轻松实现游戏刷机升级。让你游戏升级不再“肝”，轻松刷图升级，秒表大佬不是梦！…
阅读更多...
使用getline()从文件中读取一行字符串

使用getline()从文件中读取一行字符串

我们知道，getline() 方法定义在 istream 类中，而 fstream 和 ifstream 类继承自 istream 类，因此 fstream 和 ifstream 的类对象可以调用 getline() 成员方法。 当文件流对象调用 getline() 方法时，该方法的功能就变成了从指定文件…
阅读更多...
电传动无杆飞机牵引车交付用户

电传动无杆飞机牵引车交付用户

自2019年起，我们计划做电传动控制，先后做了电传动水泥搅拌罐车罐体控制（国内首创），初步理解了电机控制的特点。 20-21年接着做了10t飞机牵引车控制，还是电液控制联合的，把越野叉车的行驶控制方…
阅读更多...
Blender渲染慢?那是你还不知道这5个技巧

Blender渲染慢?那是你还不知道这5个技巧

Blender是一款功能强大且用途广泛的软件，可帮助 3D 艺术家和动画师创作出色的视觉内容。如果您使用过 Blender，您就会知道渲染可能非常耗时。渲染时间过长可能会令人烦恼并限制创造力。 在这篇文章中，我们将提供一些专家提示和想法以加快 Bl…
阅读更多...
一文搞懂MySsql的Buffer Pool

一文搞懂MySsql的Buffer Pool

Buffer Pool是什么 Buffer Pool是MySQL数据库中一个非常关键的组件。数据库中的数据最终都是存放在磁盘文件上的。但是在对数据库执行增删改查操作时，不可能直接更新磁盘上的数据。因为如果直接对磁盘进行随机读写操作，那速度是相当的慢的。随便一个大磁…
阅读更多...
软考（高项）系统分析师--论文写作技巧

软考（高项）系统分析师--论文写作技巧

文章目录 前言一、论文的结构和要求：1.1 论文的结构：1.2 论文的要求： 二、论文每段的写法：2.1 解题：2.2 摘要：2.2.1 第一段：2.2.2 第二段： 2.3 正文：2.3.1 项目背景&…
阅读更多...
TikTok美区日销二十万美金爆款黑马！胸贴赛道成功起飞！

TikTok美区日销二十万美金爆款黑马！胸贴赛道成功起飞！

从去年开始，一项名为“No bra”（无胸罩）的挑战就长期刷屏TikTok。随着平台内各大博主和明星站台发声，越来越多用户也参与其中，话题的热度逐渐走向高潮。截止到目前， TikTok上相关话题累计播放量已高达8.3亿…
阅读更多...
django admin添加自己的页面

django admin添加自己的页面

建立模型 如果要单独建一个页面，用于展示model的数据，可以新建一个model，继承自要展示的那个类 class ViewsByDayModel(ViewsByDay): # 父类为要展示的model类class Meta:proxy True # 使用代理verbose_name 每日浏览次数统计verbose_nam…
阅读更多...
仿Antd-mobile的Cascader实现省市区联动

仿Antd-mobile的Cascader实现省市区联动

为啥不直接用Cascader 级联选择组件呢？主要是因为作为老项目，已经引入了antd-mobile2.3.4，同时引入v5版本会有兼容性问题。 原始数据格式： 首先需要将后端返回的数据转为前端定义的格式，方便使用： [{&qu…
阅读更多...
jsqlparse工具拦截sql处理和拓展

jsqlparse工具拦截sql处理和拓展

前置知识 访问者模式 （Visitor Pattern）是一种行为设计模式，它允许你定义在不改变被访问元素的类的前提下，扩展其功能。通过将操作（操作或算法）从对象结构中提取出来，可以在不修改这些对象的前…
阅读更多...
机器学习与模式识别_清华大学出版社

机器学习与模式识别_清华大学出版社

contents 前言第1章 绪论1.1 引言1.2 基本术语1.3 假设空间1.4 归纳偏好1.5 发展历程1.6 应用现状 第2章 模型评估与选择2.1 经验误差与过拟合2.2 评估方法2.3 性能度量2.3.1 回归任务2.3.2 分类任务 2.4 比较检验2.5 偏差与方差2.5.1 偏差-方差分解2.5.2 偏差-方差窘境 第3章 …
阅读更多...
航空数据管控系统-②项目分析与设计：任务2：使用Git或SVN管理项目（可选任务，只介绍Git安装）

航空数据管控系统-②项目分析与设计：任务2：使用Git或SVN管理项目（可选任务，只介绍Git安装）

任务描述 1、安装Git 2、注册GitHub 3、配置本地库 4、配置远程库 5、使用Git管理项目 任务指导 分为以下几个部分完成： 学会Git的安装，帐号注册本地存储库的管理自己创建一个项目，项目名称为自己的名字，上传到代码仓库&#xff…
阅读更多...
符号速率、调制方式、码率、传输速率

符号速率、调制方式、码率、传输速率

符号速率、调制方式、码率（比特率）和传输速率在通信系统中是相互关联且重要的概念，它们之间的关系可以归纳如下： 一、定义 符号速率（Symbol Rate）： 也称波特率（Baud Rate&#xff…
阅读更多...
一文搞懂到底什么是 AQS

一文搞懂到底什么是 AQS

日常开发中，我们经常使用锁或者其他同步器来控制并发，那么它们的基础框架是什么呢？如何实现的同步功能呢？本文将详细讲解构建锁和同步器的基础框架--AQS，并根据源码分析其原理。 一、什么是 AQS？ (一) AQS…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023