当前位置：首页 > news >正文

swagger 注释说明

news 来源：原创 2025/9/6 10:14:44

一、接口注释核心字段

在 Go 的路由处理函数（Handler）上方添加注释，支持以下常用注解：

注解名称	用途说明	示例格式
`@Summary`	接口简要描述	`@Summary 创建用户`
`@Description`	接口详细说明	`@Description 通过用户名和邮箱创建新用户`
`@Tags`	接口分组标签（用于在 Swagger UI 中分类）	`@Tags users`
`@Accept`	接口接受的请求格式（如 `json`, `xml`, `form-data`）	`@Accept json`
`@Produce`	接口返回的响应格式（如 `json`, `xml`）	`@Produce json`
`@Param`	定义请求参数（路径参数、查询参数、请求体等）	`@Param id path int true "用户ID"`
`@Success`	成功响应的状态码、数据结构及描述	`@Success 200 {object} User`
`@Failure`	失败响应的状态码、数据结构及描述	`@Failure 404 {object} ErrorResponse`
`@Router`	定义接口路由路径和 HTTP 方法	`@Router /users/{id} [get]`
`@Security`	接口使用的安全策略（需先在全局定义 `@securityDefinitions`）	`@Security ApiKeyAuth`

二、`@Param` 参数详解

语法格式

@Param 参数名 参数位置 数据类型 是否必填 "描述"

参数位置

path：URL 路径参数（如 /users/{id}）
query：URL 查询参数（如 /users?name=John）
header：HTTP 头参数
body：请求体（通常用于 POST/PUT）
formData：表单数据（如文件上传）

数据类型

基本类型：int, string, boolean 等
模型对象：{object} User（需在代码中定义 User 结构体）

示例

// 路径参数
// @Param id path int true "用户ID"// 查询参数
// @Param name query string false "用户名"// 请求体（JSON）
// @Param user body User true "用户信息"// 表单文件上传
// @Param file formData file true "上传文件"

三、完整接口注释示例

示例 1：GET 请求（带路径参数）

// GetUser 获取用户详情
// @Summary 通过用户ID获取详情
// @Description 根据ID查询用户信息
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} User
// @Failure 404 {object} ErrorResponse
// @Router /users/{id} [get]
func GetUser(c *gin.Context) { ... }

示例 2：POST 请求（带请求体）

// CreateUser 创建用户
// @Summary 创建新用户
// @Description 通过JSON数据创建用户
// @Tags users
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 201 {object} User
// @Failure 400 {object} ErrorResponse
// @Router /users [post]
func CreateUser(c *gin.Context) { ... }

示例 3：文件上传（表单）

// UploadFile 上传文件
// @Summary 上传文件
// @Description 通过表单上传文件
// @Tags files
// @Accept multipart/form-data
// @Produce json
// @Param file formData file true "上传文件"
// @Success 200 {object} SuccessResponse
// @Router /upload [post]
func UploadFile(c *gin.Context) { ... }

四、模型定义注释

在结构体（请求/响应模型）上添加注释，Swagger 会自动解析字段：

// User 用户信息模型
type User struct {// 用户ID（示例值：1）ID   int    `json:"id" example:"1"`// 用户名（示例值：John）Name string `json:"name" example:"John"`// 邮箱（示例值：john@example.com）Email string `json:"email" example:"john@example.com"`
}// ErrorResponse 错误响应模型
type ErrorResponse struct {// 错误码（示例值：404）Code    int    `json:"code" example:"404"`// 错误信息（示例值："用户不存在"）Message string `json:"message" example:"用户不存在"`
}

五、常见问题

1. 文档未生成或未更新

解决：确保运行 swag init -g main.go 并重新编译代码。
检查：注释必须紧贴在路由处理函数上方，不能有空行。

2. 模型字段未显示

解决：确保结构体字段有 json 标签，例如 json:"id"。
示例值：使用 example:"1" 标签为字段添加示例值。

3. 参数绑定失败

检查：@Param 注解中的参数位置（如 path/query）与实际代码是否一致。
示例：代码中使用 c.Param("id") 时，Swagger 注解应为 @Param id path ...。

六、最佳实践

统一标签命名：如 @Tags users 用于所有用户相关接口。
详细描述参数：在 @Param 中明确参数是否必填（true/false）。
分离模型定义：将请求/响应模型放在独立的 models 包中，提升可维护性。
版本控制：在全局注解中指定 @BasePath /api/v1，便于区分 API 版本。

swagger 注释说明

一、接口注释核心字段在 Go 的路由处理函数（Handler）上方添加注释，支持以下常用注解： 注解名称用途说明示例格式Summary接口简要描述Summary 创建用户Description接口详细说明Description 通过用户名和邮箱创建新用户Tags接口分…...

编程日记 2025/9/6 10:14:44

【C++】C与C++、C++内存空间、堆与栈

C嘎嘎嘎嘎嘎~ C与C的区别与联系 C内存空间 int global_var; // 未初始化全局变量，BSS段 const char* str "Hello"; // 字符串常量text段 in数据段void func() {static int static_var; // 未初始化的静态变量，数据段int local_var; …...

编程日记 2025/9/5 18:12:26

从零训练LLM-1.训练BPE

文章目录 BPE 简介BPE (Byte-Pair Encoding) 算法训练流程BPE 编码流程BPE 评估代码参考本文基于 HF -tokenizer 训练，更便捷 BPE 简介分词器将单词从自然语言通过“词典”映射到0, 1, 36这样的数字，可以理解为数字就代表了单词在“词典”中的页码。…...

编程日记 2025/9/6 10:02:49

shield.io网站|markdown中适用的“徽标”

动态的我还没看是怎么弄，但是应该和静态的差不多，因此本文仅讨论静态徽标静态徽标效果创建方法网址：Shields.io | Shields.io 进入之后点击“Badges”标签进入网页创建徽标的页面，根据文档中对每个属性的介绍在右侧将自己预…...

编程日记 2025/9/5 14:56:02

Vue 3 自定义指令

Vue 3 是一个非常强大的前端框架，它不仅提供了简单易用的 API，还支持多种高级功能，以便开发者根据需要扩展和优化应用。在 Vue 中，自定义指令是一种非常灵活的功能，它允许我们为 DOM 元素添加特定的行为，扩…...

编程日记 2025/9/6 10:05:11

25某团校招后端开发一面

一、进程通信和线程通信方式进程通信方式管道（Pipe） 半双工通信，数据单向流动，仅用于有亲缘关系的进程（如父子进程）。通过内核缓冲区实现数据传输，如父进程写、子进程读。命名管道&#xff…...

编程日记 2025/9/6 10:08:05

音视频学习（三十四）：H264中的宏块

什么是宏块？ 在 H.264 中，宏块是编码图像时最小的处理单位。它的核心作用包括： 帧内预测（Intra Prediction）帧间预测（Inter Prediction）变换、量化、熵编码等标准定义： 一个宏块…...

编程日记 2025/9/6 3:47:26

Pandas 中透视表（`pivot_table`）和交叉表（`crosstab`）的区别

Pandas 中透视表（pivot_table）和交叉表（crosstab）的区别核心区别透视表 (pivot_table) 用于对数据进行聚合计算（如求和、均值、计数等）。支持多维度分组（行、列、甚至多层索引）。…...

编程日记 2025/9/6 10:02:51

Restful风格接口开发

目录 Restful Apifox 介绍端口号8080怎么来的？ 为什么要使用Apifox? Restful 如果请求方式是Post，那我就知道了要执行新增操作，要新增一个用户如果请求方式是Put，那就代表我要修改用户具体要对这些资源进行什么样的操…...

编程日记 2025/8/27 1:21:47

20250414| AI：RAG多路召回和融合重排序技术

好的！以下是对RAG（检索增强生成）中多路召回和融合重排序技术的详细解释，结合解释学习的视角，帮助你更好地理解和学习。这些技术是RAG系统的核心组成部分，决定了检索阶段的效果和最终生成答案的质量。我会尽…...

编程日记 2025/9/6 10:02:50

基于时间序列分解与XGBoost的交通通行时间预测方法解析

一、问题背景与数据概览在城市交通管理系统中，准确预测道路通行时间对于智能交通调度和路径规划具有重要意义。本文基于真实道路传感器数据，构建了一个结合时间序列分解与机器学习模型的预测框架。数据源包含三个核心部分：道路通行数据（new_gy_contest_traveltime_train…...

编程日记 2025/9/6 10:02:51

论文精度：HeightFormer：基于Transformer的体素高度预测在路边3D目标检测中的应用

论文地址：https://arxiv.org/pdf/2503.10777 1. 背景与问题定义 1.1 路边视觉3D检测的重要性在自动驾驶领域，车辆端的视觉感知系统面临视角局限性（如遮挡、短距离感知）和安全挑战。相比之下，路边摄像头通过高位安装，可覆盖更广的感知范围（如交叉路口、高速公路）…...

编程日记 2025/9/6 10:02:48

华为手机清理大数据的方法

清理手机最大的问题是，手动和自动清理了多次，花费了很长时间，但是只腾挪出来了一点点空间，还是有很大空间无法使用，这篇文章就告诉你怎样做，以花瓣剪辑为例，如下： 删除数据&#xff…...

编程日记 2025/9/6 10:14:44

tcp特点+TCP的状态转换图+time_wait详解

tcp特点TCP的状态转换图time wait详解目录一、tcp特点解释 1.1 面向连接 1.1.1 连接建立——三次握手 1.1.2 连接释放——四次挥手 1.2 可靠的 1.2.1 应答确认 1.2.2 超时重传 1.2.3 乱序重排 1.2.4 去重 1.2.5 滑动窗口进行流量控制 1.3 流失服务（字节…...

编程日记 2025/9/6 10:14:44

flutter 桌面应用之窗口自定义

在开发桌面软件的时候我们经常需要配置软件的窗口的大小以及位置我们有两个框架选择:window_manager和bitsdojo_window 对比bitsdojo_window 特性bitsdojo_windowwindow_manager自定义标题栏✅ 支持❌ 不支持控制窗口行为（大小/位置）✅（基本…...

编程日记 2025/9/6 10:13:10

【C++】NAN相关研究

先说结论：NAN对比一切都是false INF 对INF 是true 正无穷与正无穷比较相等，正无穷与负无穷比较不相等 window linux环境下基本相同， debug release基本相同 NAN -NAN INF -INF 不做论述 // TestNan.cpp : 此文件包含 "main" 函数。…...

编程日记 2025/9/6 10:08:57

windows下Git安装及其IDEA配置

1.下载Git安装包阿里镜像链接（建议从这里下载，速度很快） git-scm.com（官方网站，提供了各个平台（Windows、Mac、Linux）的安装程序） 选择版本号后，在选择此版本的不同包…...

编程日记 2025/9/4 22:40:21

迷你世界脚本脚本常见问题

脚本常见问题彼得兔更新时间: 2024-05-22 17:54:44 在查阅开发者学院中的脚本API时，若有任何问题或建议，欢迎通过问卷进行反馈！【点我填写问卷】 1.Block中的data在什么地方使用 data使用有具体需求,此处不建议开发者使用。开发者尽可能使…...

编程日记 2025/9/6 10:05:44

2025蓝桥杯C++ A组省赛题解

昨天打完蓝桥杯本来想写个 p y t h o n python python A A A 组的题解，结果被队友截胡了。今天上课把 C A CA CA 组的题看了，感觉挺简单的，所以来水一篇题解。这场 B B B 是一个爆搜， C C C 利用取余的性质比较好写&#…...

编程日记 2025/9/6 10:12:12

链接世界：计算机网络的核心与前沿

计算机网络引言在数字化时代，计算机网络已经成为我们日常生活和工作中不可或缺的基础设施。从简单的局域网（LAN）到全球互联网，计算机网络将数以亿计的设备连接在一起，推动了信息交换、资源共享以及全球化的进程。什…...

编程日记 2025/9/6 10:10:53

MySQL 常见存储引擎全解析：InnoDB、MyISAM、Memory 等对比与实战

一、什么是存储引擎？ 存储引擎（Storage Engine）是 MySQL 中负责数据存储与管理的底层模块。不同的存储引擎负责处理表的读写、索引维护、事务支持、崩溃恢复等机制。在创建表时可以指定使用的存储引擎： CREATE TABLE user (id…...

编程日记 2025/9/6 10:08:57

目录序号标题链接day1Python下载和开发工具介绍https://blog.csdn.net/XiaoRungen/article/details/146583769?spm1001.2014.3001.5501day2数据类型、字符编码、文件处理https://blog.csdn.net/XiaoRungen/article/details/146603325?spm1011.2415.3001.5331day3基础语法与…...

编程日记 2025/9/2 1:45:07

Python中NumPy的统计运算

在数据分析和科学计算领域，Python凭借其丰富的库生态系统成为首选工具之一，而NumPy作为Python数值计算的核心库，凭借其高效的数组操作和强大的统计运算功能，广泛应用于机器学习、信号处理、统计分析等场景。本文将系统介绍NumPy在…...

编程日记 2025/9/4 18:50:49

SQL 解析 with as

sql的运行顺序 <select id"getTrendList" parameterType"java.util.HashMap" resultType"java.util.Map"><![CDATA[WITH-- 生成连续年份列表（当前年前8年到前1年）year_range AS (SELECT EXTRACT(YEAR FROM SYSD…...

编程日记 2025/9/3 23:03:29

07-算法打卡-链表-移除链表-leetcode(203)-第七天

1 题目地址 203. 移除链表元素 - 力扣（LeetCode）203. 移除链表元素 - 给你一个链表的头节点 head 和一个整数 val ，请你删除链表中所有满足 Node.val val 的节点，并返回新的头节点。示例 1：[https://assets.leetc…...

编程日记 2025/9/2 16:54:51

抓包神器，自研EtherCAT抓包工具

大家好，博主自研了一款以太网抓包神器，可以用于EtherCAT抓包。把抓包工具接入以太网总线中，就能正常使用了。上位机软件采用wireshark。开启以下协议抓包截图如下时间戳的精度为5ns。...

编程日记 2025/8/25 19:09:45

五、adb常用命令

SDK路径下的 \Android\Sdk\platform-tools\adb.exe adb devices 查看连接的设备 adb shell getprop ro.build.version.release 查看系统版本 adb shell dumpsys window windows | findstr mFocusedApp 获取正在运行的app启动包名结果为空，我不知道是不是Android…...

编程日记 2025/9/5 17:37:31

Java第四节：idea在debug模式夏改变变量的值

作者往期文章 Java第一节：debug如何调试程序（附带源代码）-CSDN博客 Java第二节：debug如何调试栈帧链（附带源代码）-CSDN博客 Java第三节：新手如何用idea创建java项目-CSDN博客步骤一在需要修改…...

编程日记 2025/9/3 18:14:04

Java学习手册：Java反射与注解

Java反射（Reflection）和注解（Annotation）是Java语言中两个强大的特性，它们在框架开发和复杂应用中扮演着重要角色。反射允许程序在运行时检查和操作类、对象、接口、字段和方法，而注解则提供了一种元数据形…...

编程日记 2025/9/6 4:20:28

21 天 Python 计划：MySQL事务四大隔离级别深度剖析

文章目录一、事务1.1 什么是事务？1.2 事务的四大特性二、事务并发存在的问题2.1 脏读（dirty read）2.2 不可重复读（unrepeatable read）2.3 幻读三、事务的四大隔离级别实践3.1 读未提交（Read Uncommitted…...

编程日记 2025/9/2 0:31:40

IO多路复用沉浸式体验

这篇文章主要讲解一下IO多路复用常见问题，包含常见面试题，对你有帮助的话可以留个赞和关注嘛？谢谢大家支持！ 1.epoll 相比于 select/poll 的优点有哪些？ 高效的数据结构：epoll使用红黑树管理fd&#xff0…...

编程日记 2025/9/3 6:21:52

音视频学习（三十三）：GOP详解

GOP 概念 GOP（图像组）是视频编码中一组帧的集合(按相关性分组)，它从一个关键帧（I帧）开始，后面跟随若干个参考帧（P帧）和预测帧（B帧）。其结构决定了视频帧的压…...

编程日记 2025/8/31 13:14:35

部署YUM仓库

目录一.YUM 1.1yum概述 1.2yum的实现 1.3yum服务的组成 1.4yum服务实现过程 1.5yum配置文件位置二.yum相关命令三.搭建yum仓库的方式 3.1使用HTTP方式搭建yum仓库准备工作（服务端和客户端都需要做） 服务端客户端 3.2使用ftp方式搭建yu…...

编程日记 2025/9/3 0:35:04

中位数学习（低估它了）

-----------------------------------------------------------------中位数------------------------------------------------------- 中位数有一个很好的性质：假设有一批数据，你想找一个数，使得这批数据与它差的绝对值的和最小&#xff0…...

编程日记 2025/9/5 3:46:15

音视频转换器 AV 接口静电保护方案

方案简介音视频转换器是将音视频（AV）信号转换成其他格式或信号类型的设备或软件。它能够实现大多数视频、音频以及图像格式之间的转换，包括但不限于 RMVB、AVI、 MP4、MOV 等常见格式，同时也支持将不同采样率、位深度、声道数…...

编程日记 2025/9/4 14:13:03

蓝桥杯嵌入式第十二届省赛程序设计1（超简单版）

此程序只需要会C语言数组，结构体(struct)，for , if , switch(也可以用if)就能够实现。引脚设置： 引脚配置（参照笔记）： 代码部分： /* USER CODE END Header */ /* Includes ------------------…...

编程日记 2025/8/25 5:44:59

CSS 链接样式学习笔记

在网页设计中，链接（<a> 标签）是不可或缺的元素，通过 CSS 可以对链接进行丰富的样式设置，从而提升用户体验和页面美观度。以下是关于 CSS 链接样式的详细学习笔记。一、链接的四种状态链接有四种不同的状态&a…...

编程日记 2025/9/1 18:18:08

有ts文件却无法ts出来解决办法

一开始报错是报这个，但是我其实完全看不懂为什么原因是这个打开某个test就行了...

编程日记 2025/8/17 19:02:30

javaSE.Lambda表达式

如果一个接口中有且只有一个待实现的抽象方法，那么我们可以将匿名内部类简写为Lambda表达式。简写规则标准格式： （【参数类型参数名称，】...） -> {代码语句， 包括返回值} 只有一行花括号{}可以省略。…...

编程日记 2025/8/17 21:05:09

Web渗透之文件包含漏洞

文件包含漏洞原理 1、源代码 <?php$filename $_GET[filename]; include $filename; //或include_once,require,require_onceecho "欢迎来到PHP的世界.";?> 2、利用条件 php.ini中alllow_url_fopenOn(默认开启)和allow_url_includeOff(默认关闭)要开启…...

编程日记 2025/8/28 12:12:43

费马引理和罗尔定理

cheer 向……欢呼，使高兴，欢呼，欢呼，愉快前言区间平均值费马引理罗尔三步万能构造原函数的方法什么时候用罗尔定理计划拉格朗日需要记忆的不等式柯西中值定理泰勒高阶导数判断极值最后前言继续学习。今天争取把讲义和作业题都…...

编程日记 2025/9/5 17:49:40

【合新通信】浸没式液冷中低成本冷媒开发的最新进展

浸没式液冷光模块是一种结合高效散热技术与光通信的新型解决方案，主要用于数据中心、超算中心等高密度计算场景。其核心特点是通过将光模块直接浸入绝缘冷却液中（如矿物油、氟化液等），实现高效散热和节能降耗。低成本冷却液的研发…...

编程日记 2025/9/6 9:46:05

【开发记录】服务外包大赛记录

参加服务外包大赛的A07赛道中，最近因为频繁的DEBUG，心态爆炸记录错误以防止再次出现错误浪费时间。。。 2025.4.13 项目在上传图片之后会自动刷新没有等待后端返回 Network中的fetch /upload显示canceled. 然而这是使用了VS的live Server插件才这样&…...

编程日记 2025/9/3 0:35:05

智能指针之设计模式1

本文探讨一下智能指针和GOF设计模式的关系，如果按照设计模式的背后思想来分析，可以发现围绕智能指针的设计和实现有设计模式的一些思想体现。当然，它们也不是严格意义上面向对象的设计模式，毕竟它们没有那么分明的类层次体系&…...

编程日记 2025/9/3 17:38:28

Spring Boot 中应用的设计模式

Spring Boot 中应用的设计模式详解 Spring Boot 作为 Spring 框架的扩展，广泛使用了多种经典设计模式。以下是主要设计模式及其在 Spring Boot 中的具体应用： 一、创建型模式 1. 工厂模式 (Factory Pattern) 应用场景： BeanFactory 和 Ap…...

编程日记 2025/8/31 8:45:03

23种GoF设计模式

GoF（Gang of Four）设计模式是由四位计算机科学家 Erich Gamma、Richard Helm、Ralph Johnson 和 John Vlissides 合著的书籍《Design Patterns: Elements of Reusable Object-Oriented Software》中提出的设计模式目录一、创建型模式（Cre…...

编程日记 2025/8/31 2:33:35

Python实例题：Python实现中文错别字高亮系统

目录 Python实例题题目安装依赖库代码实现代码解释运行思路注意事项 Python实例题题目 Python实现中文错别字高亮系统安装依赖库在开始之前，你需要安装 pycorrector 和 rich 库。可以使用以下命令进行安装： pip install pycorrecto…...

编程日记 2025/9/1 7:24:34

【第三十一周】ViT 论文阅读笔记

ViT 摘要Abstract文章信息引言方法Patch EmbeddingPatch Position EmbeddingTransformer EncoderMLP Head整体架构CNN的归纳偏置代码实现实验结果总结摘要本篇博客介绍了Vision Transformer（ViT），这是一种突破性的图像分类模型&#xff…...

编程日记 2025/9/3 10:44:38

射频（RF）静电放电防护方案

方案简介射频（RF）是 Radio Frequency 的缩写，表示可以辐射到空间的电磁频率，频率范围从 300kHz～300GHz 之间。射频就是射频电流，简称 RF，它是一种高频交流变化电磁波的简称。射频天线是一…...

编程日记 2025/9/5 14:38:58

【redis进阶三】分布式系统之主从复制结构(1)

目录一为什么要有分布式系统？ 二分布式系统涉及到的非常关键的问题：单点问题三学习部署主从结构的redis (1)创建一个目录 (2)进入目录拷贝两份原有redis (3)使用vim修改几个选项 (4)启动两个从节点服务器 (5)建立复制，要想配…...

编程日记 2025/8/22 5:08:06

一、接口注释核心字段

二、@Param 参数详解

语法格式

参数位置

数据类型

示例

三、完整接口注释示例

示例 1：GET 请求（带路径参数）

示例 2：POST 请求（带请求体）

示例 3：文件上传（表单）

四、模型定义注释

五、常见问题

1. 文档未生成或未更新

2. 模型字段未显示

3. 参数绑定失败

六、最佳实践

相关文章：

二、`@Param` 参数详解