Swagger-go学习笔记

news2024/10/6 4:06:16

目录

    • Swagger的作用
      • 背景
      • Swagger介绍
    • Swagger的基本使用
      • 1. 使用步骤
      • 2. 添加注释
      • 3. 生成接口文档数据
      • 4. 引入gin-swagger
      • 5. 测试结果
      • 6. 使用Token
    • Swagger-go的中文文档
      • 通用API信息
      • API操作
      • MIME类型
      • 参数类型
      • 数据类型

Swagger的作用

背景

在传统的前端端分离的项目中，会使用接口文档来统一前后端的接口，一个接口应该包含以下信息：

  1. 接口的标题（如：用户登录）
  2. 接口的请求方法（如：post）
  3. 接口的描述（如：通过用户名和密码进行登录，登录成功后返回用户 id 和权限 token）
  4. 接口的请求参数（如：Query 参数：username string 登录用户名 必需 password string 登录密码 必需）
  5. 接口的返回响应（如：HTTP 状态码: 200。内容格式: JSON。数据结构<就是返回的参数规定，哪些参数，参数类型，参数是否必须，参数的含义>）
  6. 接口的路径（如：/douyin/user/login/）

其实接口文档除了要包含这些信息以外，可能还需要有一些代码示例以及参数的示例，毕竟有时候干巴巴的文字看起来很难懂。

Swagger介绍

在前后端分离的项目开发过程中，如果后端开发人员能够提供一份清晰明了的接口文档，那么就能极大地提高前后端开发人员的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的，而且后续接口文档的维护也十分耗费精力。最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新，而Swagger正是那种能帮我们解决接口文档问题的工具。

Swagger的基本使用

1. 使用步骤

以Gin框架为例，使用gin-swagger库，使用Swagger 2.0生成RESTful API文档。项目的demo代码地址：。

使用gin-swagger一般需要下面三个步骤：

  • 按照swagger要求给接口代码添加声明式注释，具体参照声明式注释格式。
  • 使用swag工具扫描代码自动生成API接口文档数据
  • 使用gin-swagger渲染在线接口文档页面

2. 添加注释

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

// @title blogWebsite
// @version 2.0
// @description 这是一个blogWebsite的demo项目，最初用来练习docker compose。目前项目中有很多接口还没有开发完成
// @termsOfService http://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 /

在你代码中处理请求的接口函数（通常位于controller层）按如下方式写上注释。

type responseUser struct {
	Msg string
	Id  uint64
}

// AddUser
// @Summary 添加用户接口
// @Description 从前端获取用户名和密码用来添加一个用户
// @Tags 用户管理
// @Accept application/json
// @Produce application/json
// @Param username query string true "用户名"
// @Param password query string true "密码"
// Success 200 {object} responseUser
// @Router /addUser [post]
func AddUser(c *gin.Context) {
	username := c.Query("username")
	password := c.Query("password")

	//查询用户名和密码是否为空
	if username != "" && password != "" {
		//查询用户名是否重复
		result := service.SelectUserIfExist(username)
		if result == 1 {
			res := responseUser{
				Msg: "用户名已被使用",
			}
			c.JSON(http.StatusOK, res)
		} else {
			id := service.Register(username, password)
			res := responseUser{
				Msg: "用户注册成功",
				Id:  id,
			}
			c.JSON(http.StatusOK, res)
		}
	} else {
		res := responseUser{
			Msg: "用户名或密码不能为空",
		}
		c.JSON(http.StatusOK, res)
	}
}

type responsePost struct {
	Msg string
	Id  uint64
}

// AddPost
// @Summary 添加文章接口
// @Description 从前端获取文章标题，文章内容和用户ID用来添加文章
// @Tags 文章管理
// @Accept application/json
// @Produce application/json
// @Param title query string true "文章标题"
// @Param context query string true "文章内容"
// @Param userID query string true "用户ID"
// @Success 200 {object} responsePost
// @Router /addPost [post]
func AddPost(c *gin.Context) {
	title := c.Query("title")
	context := c.Query("context")
	userID := c.Query("userID")

	id, err := strconv.Atoi(userID) // 将字符串类型的id转换为int类型
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	if title != "" {
		result := service.AddPost(title, context, id)
		responsePost := responsePost{
			Msg: "添加文章成功",
			Id:  result.PostID,
		}
		c.JSON(http.StatusOK, responsePost)
	} else {
		responsePost := responsePost{
			Msg: "文章标题不能为空",
		}
		c.JSON(http.StatusOK, responsePost)
	}
}

3. 生成接口文档数据

编写完注释后，使用以下命令下载和安装swagger的cmd命令：

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

在项目根目录执行以下命令，使用swag工具生成接口文档数据。

swag init

执行完上述命令后，如果你写的注释格式没问题，此时你的项目根目录下会多出一个docs文件夹。

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

4. 引入gin-swagger

下载gin-swagger的相关包

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

在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容。

// 这是你的注册路由的文件
import (
	_ "docker_compose_blog/docs"  // 千万不要忘了导入把你上一步生成的docs文件夹的路径
	swaggerFiles "github.com/swaggo/files"
	gs "github.com/swaggo/gin-swagger"
)

注册swagger api相关路由

// 在你注册路由的文件中添加
r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

把你的项目程序运行起来（重新go build，然后再运行），打开浏览器访问 http://localhost:8080/swagger/index.html 就能看到Swagger Api文档了。

需要注意的是：每次修改注释后都必须要重新swag init然后go build，修改才会生效。

5. 测试结果

这是main函数上面注释生成的项目描述信息。

image-20231010150731357

由于有两种Tags（文章管理和用户管理），相同的Tags会被分为一类。如下所示：

image-20231010154145489

先在用户管理中添加一个用户。点击Try it out就可以输入用户名和密码。

image-20231010154354826

点击Execute就可以提交请求，可能会遇到跨域问题，请自行解决。最后返回结果如下：

image-20231010155914780

现在测试文章管理的接口。测试结果如下：

image-20231010160249734

查询数据库，发现一切正常。

image-20231010160329438

6. 使用Token

如果前后端在交互过程中涉及到token的传递，那么会有以下几种情况。

  1. 如果前端将token作为query参数传递给后端，那么很简单，后端只需要把token当作query参数正常接收就可以了。
# 前端发送axios
axios.delete(`http://127.0.0.1:8080/admin/deleteBlog?title=${row.id}&token=${token}`)

# 后端的注释
// @Param token query string true "Token"
  1. 前端将token放在请求头中，那么后端需要执行以下步骤。
# 前端发送axios
const token = localStorage.getItem('token');
const response = await axios.get('http://127.0.0.1:8080/admin/getPubTimeData', {
      headers: {
        Authorization: `Bearer ${token}`,
      }

# 后端在接口注释中要添加以下内容
@Security ApiKeyAuth
    
# 接下来需要在swagger.yaml文件中写入以下内容（里面的ApiKeyAuth这个名字需要和@Security注释后面的内容保持一致）
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: Authorization

Swagger-go的中文文档

以上就完成了swagger的基本使用。其实关于Swagger还有很多东西，这是一个中文文档：SwaggerGo中文文档。下面是一些官方文档中比较常见注释的解释。

通用API信息

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

API操作

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

MIME类型

别名MIME Type
jsonapplication/json
xmltext/xml
plaintext/plain
htmltext/html
mpfdmultipart/form-data
x-www-form-urlencodedapplication/x-www-form-urlencoded
json-apiapplication/vnd.api+json
json-streamapplication/x-json-stream
octet-streamapplication/octet-stream
pngimage/png
jpegimage/jpeg
gifimage/gif

参数类型

  • query
  • path
  • header
  • body
  • formData

数据类型

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

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

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

相关文章

JAXB 使用记录 bean转xml xml转bean 数组 继承

JAXB 使用记录 bean转xml xml转bean 数组 继承

JAXB 使用记录 部分内容引自 https://blog.csdn.net/gengzhy/article/details/127564536 基础介绍 JAXBContext类&#xff1a;是应用的入口&#xff0c;用于管理XML/Java绑定信息 Marshaller接口&#xff1a;将Java对象序列化为XML数据 Unmarshaller接口&#xff1a;将XML数…
阅读更多...
数字孪生和数据分析：数字化时代的力量结合

数字孪生和数据分析：数字化时代的力量结合

在当今数字化时代&#xff0c;数据是无处不在的。企业、政府和个人不仅生成了大量数据&#xff0c;还寻求从中获取有价值的信息以进行更好的决策。在这个背景下&#xff0c;数字孪生和数据分析成为了迎合这一需求的两个关键概念。本文带大家一起探讨二者之间相辅相成的关系。 一…
阅读更多...
黑马店评-04缓存更新策略,保证MySQL数据库中的数据和Redis中缓存的数据一致性

黑马店评-04缓存更新策略,保证MySQL数据库中的数据和Redis中缓存的数据一致性

缓存更新策略(数据一致) 更新策略 缓存更新是Redis为了节约内存而设计出来的机制,当我们向Redis插入太多数据时就会导致缓存中的数据过多,所以Redis会对部分数据进行更新即淘汰 低一致性需求(数据长久不发生变化): 使用内存淘汰机制,例如店铺类型信息的查询缓存,因为这部分…
阅读更多...
day02_运算符_if

day02_运算符_if

零、今日内容 1.运算符 2.scanner 3.if,ifelse,elseif 复习 学习方法: 睡觉前过电影(1jdk,配置环境变量2idea使用3HelloWorld程序解释 4变量5数据类型6String) 主方法是每次都要写的,因为代码要执行(psvm) 输出语句每次都要写的,因为要看结果(sout) 1.声明变量的语法格式 数据类…
阅读更多...
网络安全（黑客）—0基础学习手册

网络安全（黑客）—0基础学习手册

目录梗概 一、自学网络安全学习的误区和陷阱 二、学习网络安全的一些前期准备 三、网络安全学习路线 四、学习资料的推荐 想自学网络安全&#xff08;黑客技术&#xff09;首先你得了解什么是网络安全&#xff01;什么是黑客&#xff01; 网络安全可以基于攻击和防御视角来…
阅读更多...
Git【入门】从安装到会用（千字总结●超详细）

Git【入门】从安装到会用（千字总结●超详细）

我的个人主页&#xff1a;☆光之梦☆_C语言基础语法&#xff08;超详细&#xff09;,【java入门】语法总结-CSDN博客 创作不易&#xff0c;如果能帮到你就好 注&#xff1a;你的 &#x1f44d;点赞 ⭐收藏 &#x1f4dd;评论 是对博主最大的支持与鼓励喔 认真看完这篇文章&am…
阅读更多...
极智AI | 能够轻松构建大模型端到端应用的LangChain 到底是什么

极智AI | 能够轻松构建大模型端到端应用的LangChain 到底是什么

欢迎关注我的公众号 [极智视界]，获取我的更多经验分享 大家好，我是极智视界，本文来介绍一下 能够轻松构建大模型端到端应用的 LangChain，到底是什么。 邀您加入我的知识星球「极智视界」，星球内有超多好玩的项目实战源码下载，链接：https://t.zsxq.com/0aiNxERDq 先上官…
阅读更多...
Cesium热力图

Cesium热力图

二、代码 <!doctype html> <html><head><meta charset"utf-8"><link rel"stylesheet" href"./css/common.css"><title>热力图</title><script src"./js/config.js"></script>…
阅读更多...
手动实现SpringMVC底层机制

手动实现SpringMVC底层机制

手动实现SpringMVC底层机制 &#x1f41f;准备工作&#x1f34d;搭建SpringMVC底层机制开发环境 实现任务阶段一&#x1f34d;开发ZzwDispatcherServlet&#x1f966;说明: 编写ZzwDispatcherServlet充当原生的DispatcherServlet(即核心控制器)&#x1f966;分析代码实现&#…
阅读更多...
基于点标签的目标检测与计数深度学习框架盘点

基于点标签的目标检测与计数深度学习框架盘点

(1)P2PNet <1>P2PNet提出 论文出处&#xff1a;Rethinking Counting and Localization in Crowds: A Purely Point-Based Framework 论文链接&#xff1a;https://arxiv.org/abs/2107.12746 开源代码&#xff1a;https://github.com/TencentYoutuResearch/CrowdCount…
阅读更多...
物联网AI MicroPython传感器学习 之 MQ136硫化氢传感器

物联网AI MicroPython传感器学习 之 MQ136硫化氢传感器

学物联网&#xff0c;来万物简单IoT物联网&#xff01;&#xff01; 一、产品简介 MQ136 是一种硫化氢检测传感器&#xff0c;感应范围为 1 - 200ppm。传感元件是 SnO2&#xff0c;它在清洁空气中的电导率较低。当存在 H₂S 气体时&#xff0c;传感器的电导率随着气体浓度的升…
阅读更多...
Gralloc ION DMABUF in Camera Display

Gralloc ION DMABUF in Camera Display

目录 Background knowledge Introduction ia pa va and memory addressing Memory Addressing Page Frame Management Memory area management DMA IOVA and IOMMU Introduce DMABUF What is DMABUF DMABUF 关键概念 DMABUF APIS –The Exporter DMABUF APIS –The…
阅读更多...
PyTorch模型的多种导出方式提供给其他程序使用

PyTorch模型的多种导出方式提供给其他程序使用

PyTorch模型的多种导出方式提供给其他程序使用 flyfish PyTorch模型的多种导出方式 PyTorch模型的多种导出方式提供给其他程序使用1 模型可视化2 预训练模型3 ONNX模型导出有输入有输出TRAINING导出方式EVAL导出方式 4 自定义输入输出的名字&#xff0c;并可批量推理5 导出JI…
阅读更多...
PyG两个data Datsaset v.s. InMemoryDataset

PyG两个data Datsaset v.s. InMemoryDataset

可以看到InMemoryDataset 对CPU更加友好 https://pytorch-geometric.readthedocs.io/en/latest/modules/data.html#pytorch-lightning-wrappers
阅读更多...
Linux下C++编程-进度条

Linux下C++编程-进度条

引言&#xff1a;本篇主要在linux下的C实现进度条的功能。按照多文件编程&#xff0c;同时使用Makefile文件完成多文件的编译、连接。 首先创建头文件&#xff1a; 1. progress.h #pragma once #include <iostream> #include <cstring> #include <iomanip>…
阅读更多...
Navicat定时任务

Navicat定时任务

Navicat定时任务 1、启动Navicat for MySQL工具&#xff0c;连接数据库。 2、查询定时任务选项是否开启 查询命令&#xff1a;SHOW VARIABLES LIKE ‘%event_scheduler%’; ON表示打开&#xff0c;OFF表示关闭。 打开定时任务命令 SET GLOBAL event_scheduler 0; 或者 SET G…
阅读更多...
elasticsearch 8.5.3问题记录

elasticsearch 8.5.3问题记录

一&#xff1a;解决 elasticsearch 高版本 warning: ignoring JAVA_HOMEC:\Program Files\Java\jdk-11&#xff1b; using bundled JDK if defined JAVA_HOME (set JAVA_HOME%JAVA_HOME%; )示例版本Elasticsearch 8.5.3 可以与 JDK 11 兼容&#xff0c;但不支持 JDK 17。确保选…
阅读更多...
离散数学 期末复习

离散数学 期末复习

离散数学 期末复习 图片过多&#xff0c;若无法显示&#xff0c;请转至 https://chenhaotian.top/study/discrete-mathematics-final-review/ 访问全文 发布于 2023-06-18 第 1 章 命题逻辑 1.2 等值演算 真值表法 等值演算法 题&#xff1a;等值演算 题&#xff1a;等值演…
阅读更多...
python 学习随笔 5

python 学习随笔 5

函数 在python中&#xff0c;函数也是对象。 def func():""" 这是文档字符串"""print("Hello World")fun带参数函数 函数和变量注解 def calc(a:int, b:int) -> int: # 为函数的形参和返回值标注类型return a b print(calc(1,3…
阅读更多...
C语言重点突破（2）指针（三）

C语言重点突破（2）指针（三）

本章重点 1. 函数指针 2. 函数指针数组3. 指向函数指针数组的指针 4. 回调函数 1.函数指针 首先可以明确的是&#xff0c;函数指针和数组指针的类型都是指针类型&#xff0c;用来存放地址的&#xff0c;数组指针存放数组的地址&#xff0c;而函数指针存放的便是函数的地址。 …
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023