Go-Gin-example 第五部分 加入swagger

上一节链接

swagger

为什么要用swagger

问题起源于 前后端分离

  • 后端:后端控制层,服务层,数据访问层【后端团队】
  • 前端:前端控制层,视图层,【前端团队】
    所以产生问题:前后端联调,前端和后端人员无法做到及时协商,解决问题,导致问题爆发

什么是swagger

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

  • 号称世界上最流行的api框架
  • Restful Api文档在线自动生成工具==》api文档和api定义开发

本文目标

完成本文所搭建的gin-example项目的api文档,自动生成接口文档。

安装swag

$ go get -u github.com/swaggo/swag/cmd/swag@v1.6.5

将swag添加到全局的可执行文件夹下

mv $GOPATH/bin/swag /usr/local/go/bin

验证安装是否成功

尝试以下命令是否能够正常执行

$ swag -v

安装 gin-swagger

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

编写api注释–如何与gin集成

注释格式文档
如何与gin集成部分
Swagger 中需要将相应的注释或注解编写到方法上,再利用生成器自动生成说明文件

  1. 在router.go(管理路由的文件)中引用swagger:
    针对swagger新增初始化动作和对应的路由规则
    import "github.com/swaggo/gin-swagger" // gin-swagger middleware
    import "github.com/swaggo/files" // swagger embed files
    
  2. router.go源代码中添加通用的api注释
    这里可以选择main.go中进行通用注释,为了方便我们从管理路由的文件进行注释
    这里由于是学习用的项目,我们这里选择简单添加标题title,版本version,以及主机名称及端号host
...
// @title			gin-example
// @version		1.0
// @host			localhost:8000
func InitRouter() *gin.Engine {...
}
...
  1. 添加相关的api操作注释
    api操作的注释文档链接
    我们这里选择添加简单的介绍summary、传入的参数相关信息Param、成功的代码其返回的相关信息success、其路由地址等相关信息router
  • auth.go
package apiimport (
...
)
...// @Summary 生成用户token
// @Param username query string true "username"
// @Param password query string true "password"
// @Success 200 {string} json "{"code":200."data":{},"msg":"ok"}"
// @Router /auth [get]
func GetAuth(c *gin.Context) {
...
}
  • article.go
package v1import (
...
)// @Summary 获取单个文章
// @Produce  json
// @Param id path int true "id"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/articles [get]
func GetArticle(c *gin.Context) {
...
}// @Summary 获取文章列表
// @Produce  json
// @Param state query int true "state"
// @Param tag_id query int true "tag_id"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/articles [get]
func GetArticles(c *gin.Context) {
...
}// @Summary 新增文章
// @Produce  json
// @Param tagId query int true "tagId"
// @Param title query string true "title"
// @Param desc query string true "desc"
// @Param content query string true "content"
// @Param createdBy query string true "createdBy"
// @Param state query int true "state"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddArticle(c *gin.Context) {
...
}// @Summary 修改文章
// @Produce  json
// @Param id path int true "id"
// @Param tagId query int true "tagId"
// @Param title query string true "title"
// @Param desc query string true "desc"
// @Param content query string true "content"
// @Param modifiedBy query string true "modifiedBy"
// @Param state query int false "state"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func EditArticle(c *gin.Context) {
...
}// @Summary 删除文章
// @Produce  json
// @Param id path int true "id"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func DeleteArticle(c *gin.Context) {
...
}
  • tag.go
package v1import (
...
)// @Summary 查询标签
// @Produce json
// @Param name query string true "name"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [get]
func GetTags(c *gin.Context) {
...
}// @Summary 新增文章标签
// @Produce  json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddTag(c *gin.Context) {
...
}// @Summary 修改文章标签
// @Produce  json
// @Param id path int true "ID"
// @Param name query string true "ID"
// @Param state query int false "State"
// @Param modified_by query string true "ModifiedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags/{id} [put]
func EditTag(c *gin.Context) {
...
}// @Summary 删除文章标签
// @Produce  json
// @Param name path int true "id"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags{id} [delete]
func DeleteTag(c *gin.Context) {
...
}

生成说明文件

进入到项目的项目根目录中,执行初始化命令
由于我们的总的通用api注释没有写在main.go中,而是在router.go中,我们使用-g标识符来告知swag,如果直接在main.go中进行api注释的话可以直接swag init

swag init -g routers/router.go

生成完毕之后会在根目录下生成docs文件夹
当前项目的目录树:

.
├── conf
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── middleware
│   └── jwt
├── models
├── pkg
│   ├── e
│   ├── logging
│   ├── setting
│   └── util
├── routers
│   └── api
│       └── v1
└── runtime└── logs

验证

运行并访问http://127.0.0.1:8000/swagger/index.html ,查看是否能够正常运行

在这里插入图片描述

之后各种操作都简单便利啦

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

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

相关文章

Keepalived+LVS构建高可用集群

目录 一、Keepalive基础介绍 1. Keepalive与VRRP 2. VRRP相关技术 3. 工作原理 4. 模块 5. 架构 6. 安装 7. Keepalived 相关文件 7.1 配置组成 7.2 全局配置 7.3 VRRP实例配置(lvs调度器) 7.4 虚拟服务器与真实服务器配置 二、Keepalived…

HTML静态网页成品作业(HTML+CSS)——花主题介绍网页设计制作(1个页面)

🎉不定期分享源码,关注不丢失哦 文章目录 一、作品介绍二、作品演示三、代码目录四、网站代码HTML部分代码 五、源码获取 一、作品介绍 🏷️本套采用HTMLCSS,未使用Javacsript代码,共有1个页面。 二、作品演示 三、代…

C语言:基于单链表实现的泊车管理系统

一、需求 (1)管理员方账号登录; (2)车位管理显示:车位状态; (3)收费管理:小轿车 5元/小时,面包车6元/小时,大货车或客车7元/小时&a…

node.js 下 mysql2 的 CURD 功能极简封装

此封装适合于使用 SQL 直接操作数据库的小型后端项目,更多功能请查阅MySQL2官网 // 代码保存到单独的 js 文件const mysql require(mysql2/promise)const debug true let conn/*** 执行 SQL 语句* param {String} sql* param {*} params* returns {Array}*/ const…

ChatGPT提示技巧——零,一和少量示例提示

ChatGPT提示技巧——零,一和少量示例提示 ​ 零样本(zero-shot)、少样本(few-shot)和单样本(one-shot)提示是用于在最少或没有示例的情况下从ChatGPT生成文本的技巧。这些技巧用于当某个具体任务有限定数据的时候或者任务是新的并且没有很好的定义的时候。 提示格…

JVM的各种垃圾回收器(GC)

1. Serial GC Serial GC 是用于单线程环境的垃圾回收器,它使用复制算法(Copy)进行年轻代的垃圾回收,而老年代则使用标记-整理(Mark-Compact)算法。由于它在进行垃圾回收时会暂停其他所有的工作线程&#xf…

严密的逻辑会不会影响创新

严密的逻辑可以对创新产生积极的影响,也可能对创新产生负面的影响。以下是两种可能的情况: 积极影响:严密的逻辑可以帮助创新者更好地理解问题,并找到解决问题的方法。它可以帮助人们分析和评估不同的创新想法,以确定哪…

设计模式之——简单工厂模式

上图为简单工厂模式的架构图。 1,产品(Product) 将会对接口进行声明。 2,具体产品(Concrete Products)是产品接口的不同实现。 3,创建者(Concrete Creators)将会重写基…

二刷代码随想录算法训练营第十五天 |层序遍历 10、 226.翻转二叉树 、101.对称二叉树 2

目录 一、102. 二叉树的层序遍历 二、226. 翻转二叉树 三、101. 对称二叉树 一、102. 二叉树的层序遍历 题目链接:力扣 文章讲解:代码随想录 视频讲解: 讲透二叉树的层序遍历 | 广度优先搜索 | LeetCode:102.二叉树的层序遍历…

TCP传输收发

TCP通信: TCP发端: socket connect send recv close TCP收端: socket bind listen accept send recv close 1.connect int connect(int sockfd, const struct sockaddr *addr, socklen_t ad…

先缓存第二集抖音接入 ,最近加班猛,就分享简单的知识,如何使用:关于使用replace的用法正则表达式

1、需求:比如在cocos creator策划让你制作一个预制体,标题要读取配置,然后中间显示的内容要滚动的,要做成一个通用的,然后给到的配置表是这样子的: 配置表:假设字段是这样子的 content "内容标题&…

Intel 历代 CPU 型号

以下所有型号均为一整个系列,加上前缀、后缀啥的,差异化早在1970年代就被美国资本家玩明白了,充分地占领了市场。 CPU型号时间位数频率内存寻址地址总线说明400419714位740KHz640B4001(ROM),4002(RAM),4003(register)…

20个Python函数程序实例

前面介绍的函数太简单了: 以下是 20 个不同的 Python 函数实例 下面深入一点点: 以下是20个稍微深入一点的,使用Python语言定义并调用函数的示例程序: 20个函数实例 简单函数调用 def greet():print("Hello!")greet…

寻找最近的公共父视图

题目 求两个视图的最近公共父视图 暴力解法 采用的是两个 while 循环嵌套迭代来查询最近的公共父视图, 时间复杂度 O(n), 详见 Masonry 的实现: - (instancetype)mas_closestCommonSuperview:(MAS_VIEW *)view {MAS_VIEW *closestCommonSuperview nil;MAS_VIEW *…

css-vxe-form-item中输入框加自定义按钮(校验位置错误)

1.浮动错误效果 提示内容不对 2.不使用浮动&#xff0c;使用行内块元素 代码如下 <vxe-form-item title"yoyo:" field"assembleWorkNo" span"8"><template #default><vxe-input style"width:70%;display:inline-block;&quo…

NLP神器Transformers入门简单概述

在这篇博客中,我们将深入探索 🤗 Transformers —— 一个为 PyTorch、TensorFlow 和 JAX 设计的先进机器学习库。🤗 Transformers 提供了易于使用的 API 和工具,使得下载和训练前沿的预训练模型变得轻而易举。利用预训练模型不仅能减少计算成本和碳足迹,还能节省从头训练…

全天候购药系统(微信小程序+web后台管理)

PurchaseApplet 全天候购药系统&#xff08;微信小程序web后台管理&#xff09; 传统线下购药方式存在无法全天候向用户提供购药服务&#xff0c;无法随时提供诊疗服务等问题。为此&#xff0c;运用软件工程开发规范&#xff0c;充分调研建立需求模型&#xff0c;编写开发文档…

Java输入和输出处理

一、Java I/O 文件、内存、键盘--->程序--->文件、内存、控制台 二、文件 相关记录或放在一起的数据的集合 思考&#xff1a; Java程序如何访问文件属性&#xff1f; 解答&#xff1a; Java API:java.io.File类 三、File类 File类的常用方法 方法名称说明boole…

maven项目结构管理统一项目配置操作

一、maven分模块开发 Maven 分模块开发 1.先创建父工程&#xff0c;pom.xml文件中&#xff0c;打包方式为pom 2.然后里面有许多子工程 3.我要对父工程的maven对所有子工程进行操作 二、解读maven的结构 1.模块1 <groupId>org.TS</groupId><artifactId>TruthS…

黑马点评-分布式锁业务

分布式锁原理和实现 分布式系统部署了多个tomcat&#xff0c;每个tomcat都有一个属于自己的jvm&#xff0c;那么假设在服务器A的tomcat内部&#xff0c;有两个线程&#xff0c;这两个线程由于使用的是同一份代码&#xff0c;那么他们的锁对象是同一个&#xff0c;是可以实现互…