go——Swagger使用

news2024/11/22 17:17:01

一. 为什么后端需要配置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 main

import (
	"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 main

import (
	"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 main

import (
	"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 docs

package main

import (
	_ "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 main

import (
	"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.coloradmin.cn/o/1894291.html

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

相关文章

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

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

自2019年起，我们计划做电传动控制，先后做了电传动水泥搅拌罐车罐体控制（国内首创），初步理解了电机控制的特点。 20-21年接着做了10t飞机牵引车控制，还是电液控制联合的，把越野叉车的行驶控制方…
阅读更多...
Python学习之小游戏--坦克大作战

Python学习之小游戏--坦克大作战

今天跟视频学习了Python实现坦克大作战小游戏，挺有意思的，一起来玩吧~ 按空格发射子弹，上下左右键实现移动，ESC键无限复活。 import pygame,time,random from pygame.sprite import Sprite SCREEN_WIDTH800 SCREEN_HEIGHT500 BG…
阅读更多...
玩机进阶教程----MTK芯片杂牌机 小品牌机型解除bl锁以及root的操作步骤解析

玩机进阶教程----MTK芯片杂牌机 小品牌机型解除bl锁以及root的操作步骤解析

在玩机过程中会遇到很多小品牌机型或者杂牌机类的。大多都使用mtk芯片。而且基本很少有官方线刷包。在这些机型中玩机首先我们要想办法导出系统来制作线刷包。以免后续解锁bl或者root出现未知故障可以恢复原系统。 那么对于这些机型该如何进行备份固件和root呢。通过博文可以初…
阅读更多...
图书借阅小程序论文（设计）开题报告

图书借阅小程序论文（设计）开题报告

一、课题的背景和意义 近些年来，随着移动互联网巅峰时期的来临，互联网产业逐渐趋于“小、轻、微”的方向发展，符合轻应用时代特点的各类技术受到了不同领域的广泛关注。在诸多产品中，被誉为“运行着程序的网站”之名的微信小程序…
阅读更多...
开始尝试从0写一个项目--前端（一）

开始尝试从0写一个项目--前端（一）

基础项目构建 创建VUE初始工程 确保自己下载了node.js和npm node -v //查看node.js的版本 npm -v //查看npm的版本 npm i vue/cli -g //安装VUE CLI 创建 以管理员身份运行 输入：vue ui 就会进入 点击创建 自定义项目名字，选择npm管理 结…
阅读更多...
什么是多态（Polymorphism）

什么是多态（Polymorphism）

什么是多态（Polymorphism） 1、多态的基本概念2、多态的实现方式2.1 方法重载（Overloading）2.2 方法重写（Overriding）2.3 接口和抽象类 3、为什么要使用多态？4、结论 💖The Begin&…
阅读更多...
启明智显Model3A芯片方案7寸高清触摸屏ZX7D00CM21S：开箱、设置与实操全攻略指南

启明智显Model3A芯片方案7寸高清触摸屏ZX7D00CM21S：开箱、设置与实操全攻略指南

一、背景 本指南将详细介绍启明智显的Model3A芯片方案下的7寸高清触摸屏ZX7D00CM21S的开箱步骤、基础设置以及实操应用。无论您是电子爱好者、开发者还是工程师，这份指南都能助您快速上手并充分利用这款触摸屏的各项功能。 二、硬件介绍 ZX7D00CM21S 7寸高清触摸屏是…
阅读更多...
500mA、低压差、低噪声、超快、无需旁路电容的CMOS LDO稳压器RT9013

500mA、低压差、低噪声、超快、无需旁路电容的CMOS LDO稳压器RT9013

一般描述 RT9013 SOT23-5封装的外观和丝印 RT9013 是一款高性能的 500mA LDO 稳压器，具有极高的 PSRR 和超低压差。非常适合具有苛刻性能和空间要求的便携式射频和无线应用。 RT9013的静态电流低至25μA，进一步延长了电池的使用寿命。RT9013 也适用于低…
阅读更多...
kafka的工作原理与常见问题

kafka的工作原理与常见问题

定义 kafka是一个分布式的基于发布/订阅模式的消息队列（message queue），主要应用于大数据的实时处理领域 消息队列工作原理 kafka的组成结构 kafka的基础架构主要有broker、生产者、消费者组构成，还包括zookeeper. 生产者负责发送…
阅读更多...
【Android源码】Gerrit安装

【Android源码】Gerrit安装

前言 如果你打开 https://android.googlesource.com/platform/manifest，就会发现，google官方管理Android源码，使用的是Gerrit。Android系统源码是非常大的，用Git肯定是不适合。对于大型项目，得用Gerrit，今…
阅读更多...
小龙虾优化24种机器学习多输入单输出回归|时序预测模型

小龙虾优化24种机器学习多输入单输出回归|时序预测模型

小龙虾优化24种机器学习多输入单输出回归|时序预测模型 文章目录 小龙虾优化24种机器学习多输入单输出回归|时序预测模型前言一、小龙虾优化基本原理二、优化机器学习模型1.COA-CNN-BiGRU-Attention回归模型2.基于小龙虾优化支持向量机的数据回归预测Matlab程序COA-SVM 多特征输…
阅读更多...
Web应用防火墙用在哪些场景？

Web应用防火墙用在哪些场景？

WAF是Web Application Firewall的缩写，翻译为“Web应用防火墙”是一种网络安全设备或服务，用于保护Web应用程序免受各种网络攻击和漏洞的影响。 WAF特别设计用于识别和阻止特定于Web应用程序的攻击，例如SQL注入、跨站脚本(XSS)、跨站请求伪造…
阅读更多...
014-GeoGebra基础篇-快速解决滑动条的角度无法输入问题

014-GeoGebra基础篇-快速解决滑动条的角度无法输入问题

有客户反馈，他的Geogebra一直有个bug，那就是输入角度最大值时总不按照他设定的展示，快被气炸了~ 目录 一、问题复现（1）插入一个滑动条（2）选择Angle（3）输入90，…
阅读更多...
MySQL学习（8）：约束

MySQL学习（8）：约束

1.什么是约束 约束是作用于表中字段上的规则，以限制表中数据，保证数据的正确性、有效性、完整性 约束分为以下几种： not null非空约束限制该字段的数据不能为nullunique唯一约束保证该字段的所有数据都是唯一、不重复的primary key主键约束…
阅读更多...
linux中与网络有关的命令

linux中与网络有关的命令

本文的命令总览 ifconfig命令 在 Linux 系统中，ifconfig 命令用于配置和显示网络接口的信息，包括 IP 地址、MAC 地址、网络状态等。同时我们也可以利用ifconfig 命令设置网络接口对应的ip地址，子网掩码等 当你使用 ifconfig 命令时&#xf…
阅读更多...
Oracle数据库中RETURNING子句

Oracle数据库中RETURNING子句

RETURNING子句允许您检索插入、删除或更新所修改的列（以及基于列的表达式）的值。如果不使用RETURNING，则必须在DML语句完成后运行SELECT语句，才能获得更改列的值。因此，RETURNING有助于避免再次往返数据库，…
阅读更多...
3D slicer

3D slicer

阅读更多...
SpringBoot 启动流程一

SpringBoot 启动流程一

SpringBoot启动流程一 我们首先创建一个新的springboot工程 我们不添加任何依赖 查看一下pom文件 我们创建一个文本文档 记录我们的工作流程 我们需要的是通过打断点实现 我们首先看一下启动响应类 package com.bigdata1421.start_up;import org.springframework.boot.Spr…
阅读更多...
Element中的日期时间选择器DateTimePicker和级联选择器Cascader

Element中的日期时间选择器DateTimePicker和级联选择器Cascader

简述：在Element UI框架中，Cascader（级联选择器）和DateTimePicker（日期时间选择器）是两个非常实用且常用的组件，它们分别用于日期选择和多层级选择，提供了丰富的交互体验和便捷的数据…
阅读更多...
Chart.js四个示例

Chart.js四个示例

示例代码在图片后面&#xff0c;点赞加关注&#xff0c;谢谢 条形图 雷达图 折线图 圆环图 完整例子代码 具体代码在干什么看粗体加重的注释 <!DOCTYPE html> <html lang"en"> <head> <meta charset"UTF-8"> <me…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023