GO 的 Web 开发系列（五）—— 使用 Swagger 生成一份好看的接口文档

news2025/1/24 11:41:28

经过前面的文章，已经完成了 Web 系统基础功能的搭建，也实现了 API 接口、HTML 模板渲染等功能。接下来要做的就是使用 Swagger 工具，为这些 Api 接口生成一份好看的接口文档。

一、写注释

注释是 Swagger 的灵魂，Swagger 是通过特定格式的注释生成接口文档的。

1.1 基础注释

这部分基础注释对全接口文档通用，指定接口文档的基础信息，可添加在 main 函数上。

注释说明示例
title必填 应用程序的名称。// @title Swagger Example API
version必填 提供应用程序API的版本。// @version 1.0
description应用程序的简短描述。// @description This is a sample server celler server.
tag.name标签的名称。// @tag.name This is the name of the tag
tag.description标签的描述。// @tag.description Cool Description
tag.docs.url标签的外部文档的URL。// @tag.docs.urlhttps://example.com
tag.docs.description标签的外部文档说明。// @tag.docs.description Best example documentation
termsOfServiceAPI的服务条款。// @termsOfServicehttp://swagger.io/terms/
contact.name公开的API的联系信息。// @contact.name API Support
contact.url联系信息的URL。 必须采用网址格式。// @contact.urlhttp://www.swagger.io/support
contact.email联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。// @contact.emailsupport@swagger.io
license.name必填 用于API的许可证名称。// @license.name Apache 2.0
license.url用于API的许可证的URL。 必须采用网址格式。// @license.urlhttp://www.apache.org/licenses/LICENSE-2.0.html
host运行API的主机（主机名或IP地址）。// @host localhost:8080
BasePath运行API的基本路径。// @BasePath /api/v1
acceptAPI 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。// @accept json
produceAPI可以生成的MIME类型的列表。值必须如“Mime类型”中所述。// @produce json
query.collection.format请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。 如果未设置，则默认为csv。// @query.collection.format multi
schemes用空格分隔的请求的传输协议。// @schemes http https
externalDocs.descriptionDescription of the external document.// @externalDocs.description OpenAPI
externalDocs.urlURL of the external document.// @externalDocs.urlhttps://swagger.io/resources/open-api/
x-name扩展的键必须以x-开头，并且只能使用json值// @x-example-key {“key”: “value”}

1.2 API 接口注释

这部分注释用于声明一个接口，可将这部分注释添加到相应的接口方法上。

注释描述
description操作行为的详细说明。
description.markdown应用程序的简短描述。该描述将从名为endpointname.md的文件中读取。
id用于标识操作的唯一字符串。在所有API操作中必须唯一。
tags每个API操作的标签列表，以逗号分隔。
summary该操作的简短摘要。
acceptAPI 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。
produceAPI可以生成的MIME类型的列表。值必须如“Mime类型”中所述。
param用空格分隔的参数。param name,param type,data type,is mandatory?,comment attribute(optional)
security每个API操作的安全性。
success以空格分隔的成功响应。return code,{param type},data type,comment
failure以空格分隔的故障响应。return code,{param type},data type,comment
response与success、failure作用相同
header以空格分隔的头字段。return code,{param type},data type,comment
router以空格分隔的路径定义。path,[httpMethod]
deprecatedrouter与router相同，但是是deprecated的。
x-name扩展字段必须以x-开头，并且只能使用json值。
deprecated将当前API操作的所有路径设置为deprecated

1.3 类型枚举

以上接口注解中用到的枚举类型的介绍。

Mime 类型枚举：

swag 接受所有格式正确的 MIME 类型, 即使匹配 */*。除此之外，swag 还接受某些 MIME 类型的别名。

AliasMIME 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请求的 url 参数
path放在请求路径中的参数
header请求 header 中的参数
body请求 body 中的参数
formDatax-www-form-urlencoded 请求是的表单参数

数据类型枚举：

数据类型对应实际类型
stringstring
integerint, uint, uint32, uint64
numberfloat32
booleanbool
结构体结构体类型

更多用法内容可参考官方文档：https://github.com/swaggo/swag/blob/master/README_zh-CN.md

1.4 示例

通用 API 示例：

以下注释指定了文档的基本信息，以及基于 apikey 方式的一种安全校验方式：

// @title Aurora Admin-API 文档
// @version v0.0.1
// @description Aurora 建站
// @contact.name nineya
// @contact.url https://www.nineya.com
// @contact.email 361654768@qq.com
// @schemes http https
// @host localhost:8888
// @BasePath /api/admin
// @produce json
// @securityDefinitions.apikey admin
// @in header
// @name Admin-Authorization

注解不能放在 @securityDefinitions 相关注解的后面，否则将不会被解析

接口 API 示例：

// @summary Upload attachment by id
// @description Upload attachment by id
// @tags attachment
// @accept json
// @produce json
// @param id path id true "Attachment id"
// @param param body request.UpdateAttachmentParam true "Attachment name and team information"
// @success 200 {object} response.Response
// @security admin
// @router /attachment/{id} [put]

二、文档生成

使用命令下载 swag：

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

使用命令生成 swag 所需的文件：

swag init

这将会扫描源程序，解析注释并生成 docs 文件夹和文档信息文件。

go-swagger

三、与 Gin 集成

下载安装 gin-swagger ：

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

导入 docs下的文件：

import (
   _ "go-project-name/docs"
)

添加 Gin 路由：

swaggerGroup := router.Group("swagger")
swaggerGroup.GET("/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

通过 /swagger/index.html 可以访问到文档：

访问 swagger 接口文档

四、多文档

我们一个系统可能包含开发者、用户、管理员多种角色，我们需要为不同的角色分别创建接口文档。

4.1 生成文档

要生成多份文档，在生成文档时就不能直接执行 swag init 命令了，需要指定更多的参数：

swag init -h
NAME:
   swag init - Create docs.go

USAGE:
   swag init [command options] [arguments...]

OPTIONS:
   --generalInfo value, -g value          API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --dir value, -d value                  API解析目录 (默认: "./")，多个目录可用逗号分隔
   --exclude value                        解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --propertyStrategy value, -p value     结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
   --output value, -o value               文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --parseVendor                          是否解析vendor目录里的go源文件，默认不
   --parseDependency                      是否解析依赖目录中的go源文件，默认不
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部，默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --parseInternal                        解析 internal 包中的go文件，默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")

可分别为每份文档执行以下命令方法生成多份文档：

swag init -g 通用API所在Go文件 -d  API解析目录 --exclude 排除的目录 -o 文档输出目录 --instanceName 文档实例名

举例小玖的结构体对象所在目录为 internal/application/param，Admin 接口所在目录为internal/application/router/api/admin，Content 接口所在目录为 internal/application/router/api/content。

Admin 文档命令：

swag init -g index.go -d internal/application/router/api/admin,internal/application/param -o ./docs/admin --instanceName=admin

Content 文档命令：

swag init -g index.go -d internal/application/router/api/content,internal/application/param -o ./docs/content --instanceName=content

注意：

-g 参数的路径相对于 -d 参数的第一个路径。

如果 -d 指定的路径下没有 Go 文件，会有 execute go list command, exit status 1, stdout:, stderr:no Go files in ... 错误提示，无影响。

4.2 与 Gin 集成

导入 docs 下的文件：

import (
   _ "go-project-name/docs/admin"
   _ "go-project-name/docs/content"
)

添加 Gin 路由：

swaggerGroup := router.Group("swagger")
swaggerGroup.GET("/admin/*any", ginSwagger.WrapHandler(
  swaggerFiles.NewHandler(), func(config *ginSwagger.Config) {
    config.InstanceName = "admin"
  }))
swaggerGroup.GET("/content/*any", ginSwagger.WrapHandler(
  swaggerFiles.NewHandler(), func(config *ginSwagger.Config) {
    config.InstanceName = "content"
  }))

通过 /swagger/admin/index.html 和 /swagger/content/index.html 可以分别访问到两份文档。

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

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

相关文章

Microsoft OneNote 图片文字提取

Microsoft OneNote 图片文字提取

Microsoft OneNote 图片文字提取 1. 文件 -> 新建 -> 我的电脑 -> 名称 -> 位置 -> 创建笔记本2. 插入图片​​​3. 复制图片中的文本References 1. 文件 -> 新建 -> 我的电脑 -> 名称 -> 位置 -> 创建笔记本 ​ 2. 插入图片 ​​​3. 复制图片…
阅读更多...
Material Design

Material Design

1.使用颜色 2. 处理文本 3.处理形状 ​​​​​​
阅读更多...
书生·浦语大模型第五课作业

书生·浦语大模型第五课作业

基础作业： 使用 LMDeploy 以本地对话、网页Gradio、API服务中的一种方式部署 InternLM-Chat-7B 模型，生成 300 字的小故事（需截图） 这里 /share/conda_envs 目录下的环境是官方未大家准备好的基础环境，因为该目录是共…
阅读更多...
161基于matlab的快速谱峭度方法

161基于matlab的快速谱峭度方法

基于matlab的快速谱峭度方法，选择信号峭度最大的频段进行滤波，对滤波好信号进行包络谱分析。输出快速谱峭度及包络谱结果。程序已调通，可直接运行。 161 信号处理 快速谱峭度 包络谱分析 (xiaohongshu.com)
阅读更多...
正则表达式与正则可视化工具：解密文本处理的利器

正则表达式与正则可视化工具：解密文本处理的利器

正则表达式与正则可视化工具：解密文本处理的利器 引言 在计算机科学和软件开发领域，正则表达式是一种强大而灵活的文本处理工具。然而，对于初学者来说，正则表达式的语法和规则可能会显得晦涩难懂。为了帮助初学者更好地理解和学…
阅读更多...
Linux第48步_编译正点原子的出厂Linux内核源码

Linux第48步_编译正点原子的出厂Linux内核源码

编译正点原子的出厂 Linux 内核源码，为后面移植linux做准备。研究对象如下： 1)、linux内核镜像文件“uImage” 路径为“arch/arm/boot”； 2)、设备树文件“stm32mp157d-atk.dtb” 路径为“arch/arm/boot/dts” 3)、默认配置文件“stm32m…
阅读更多...
nba2k24 韩旭面补

nba2k24 韩旭面补

nba2k23-24 韩旭面补 nba2k23-nba2k24通用 韩旭面补 下载地址： https://www.changyouzuhao.cn/9605.html
阅读更多...
监测Nginx访问日志502情况后并做相应动作

监测Nginx访问日志502情况后并做相应动作

今天带大家写一个比较实用的脚本哈 原理： 假设服务器环境为lnmp，近期访问经常出现502现象，且502错误在重启php-fpm服务后消失，因此需要编写监控脚本，一旦出现502，则自动重启php-fpm服务 场景： 1…
阅读更多...
代码随想录day20--二叉树的应用8

代码随想录day20--二叉树的应用8

LeetCode669.修剪二叉搜索树 题目描述： 给你二叉搜索树的根节点 root ，同时给定最小边界low 和最大边界 high。通过修剪二叉搜索树，使得所有节点的值在[low, high]中。修剪树 不应该 改变保留在树中的元素的相对结构 (即，如果没…
阅读更多...
Tied Block Convolution: 具有共享较薄滤波器的更简洁、更出色的CNN

Tied Block Convolution: 具有共享较薄滤波器的更简洁、更出色的CNN

摘要 https://arxiv.org/pdf/2009.12021.pdf 卷积是卷积神经网络（CNN）的主要构建块。我们观察到，随着通道数的增加，优化后的CNN通常具有高度相关的滤波器，这降低了特征表示的表达力。我们提出了Tied Block Convolutio…
阅读更多...
人工智能能产生情绪吗？

人工智能能产生情绪吗？

此图片来源于网络 一、人情绪的本质是什么？ 人的情绪本质是一个复杂的现象，涉及到生理、心理和社会的多个层面。以下是关于情绪本质的几种观点： 情绪的本质是生命能量的表达。情绪被认为是生命能量的一种体现，通过情绪的体验和…
阅读更多...
第四节 zookeeper集群与分布式锁

第四节 zookeeper集群与分布式锁

目录 1. Zookeeper集群操作 1.1 客户端操作zk集群 1.2 模拟集群异常操作 1.3 curate客户端连接zookeeper集群 2. Zookeeper实战案例 2.1 创建项目引入依赖 2.2 获取zk客户端对象 2.3 常用API 2.4 客户端向服务端写入数据流程 2.5 服务器动态上下线、客户端动态监听 2…
阅读更多...
基于大语言模型的AI Agents

基于大语言模型的AI Agents

代理（Agent）指能自主感知环境并采取行动实现目标的智能体。基于大语言模型（LLM）的 AI Agent 利用 LLM 进行记忆检索、决策推理和行动顺序选择等，把Agent的智能程度提升到了新的高度。LLM驱动的Agent具体是怎么做的呢&a…
阅读更多...
探索Redis特殊数据结构：Geospatial(地理位置)在实际中的应用

探索Redis特殊数据结构：Geospatial(地理位置)在实际中的应用

一、概述 Redis官方提供了多种数据类型，除了常见的String、Hash、List、Set、zSet之外，还包括Stream、Geospatial、Bitmaps、Bitfields、Probabilistic（HyperLogLog、Bloom filter、Cuckoo filter、t-digest、Top-K、Count-min sketch、Confi…
阅读更多...
「Linux」用户操作

「Linux」用户操作

root用户 su：切换账户 语法：su [–] [用户名] -：可选，表示是否在切换用户后加载环境变量，建议带上用户名：表示要切换的用户，省略时表示切换到root切换用户后，通过exit命令退回上一个…
阅读更多...
HTTP基本概念-HTTP 是什么?

HTTP基本概念-HTTP 是什么?

资料来源 : 小林coding 小林官方网站 : 小林coding (xiaolincoding.com) HTTP 是什么? HTTP 是超文本传输协议，也就是HyperText Transfer Protocol。 能否详细解释「超文本传输协议」? HTTP 的名字「超文本协议传输」，它可以拆成三个部分: 超文本传输…
阅读更多...
vue安装使用less，解决与webpack的冲突

vue安装使用less，解决与webpack的冲突

第077个 查看专栏目录: VUE ------ element UI 专栏目标 在vue和element UI联合技术栈的操控下，本专栏提供行之有效的源代码示例和信息点介绍，做到灵活运用。 提供vue2的一些基本操作：安装、引用，模板使用，computed&a…
阅读更多...
HeidiSQL安装配置（基于小皮面板（phpstudy））连接MySQL

HeidiSQL安装配置（基于小皮面板（phpstudy））连接MySQL

下载资源 对于这款图形化工具，博主建议通过小皮面板（phpstudy）来下载即可，也是防止你下载到钓鱼软件，小皮面板（phpstudy）如果你不懂是什么，请看下面链接这篇博客 第二篇：…
阅读更多...
EMC学习笔记（二十六）降低EMI的PCB设计指南（六）

EMC学习笔记（二十六）降低EMI的PCB设计指南（六）

降低EMI的PCB设计指南（六） 1.PCB布局1.1 带键盘和显示器的前置面板PCB在汽车和消费类应用中的应用1.2 敏感元器件的布局1.3 自动布线器 2.屏蔽2.1 工作原理2.2 屏蔽接地2.3 电缆屏蔽至旁路2.4 缝隙天线：冷却槽和缝隙 tips：资料主要…
阅读更多...
蓝牙BLE学习-概述

蓝牙BLE学习-概述

1. 简介 1.1 蓝牙发展历程 蓝牙，直接来自于一位国王的名字--King Harald ‘Bluetooth Gromsson。这位国王因两件事留名于史，其一是在公园958年统一了丹麦和挪威，其二是在其死后，其牙齿呈现出暗蓝色的颜色，因而得名蓝牙…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023