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

经过前面的文章，已经完成了 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 可以分别访问到两份文档。

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

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈qq邮箱809451989@qq.com，一经查实，立即删除！

相关文章

leaflet 显示自己geoserver发布的中国地图

leaflet 显示自己geoserver发布的中国地图

安装vscode 安装 通义灵码 问题&#xff1a; 用leaflet显示一个wms地图 修改下代码&#xff0c;结果如下&#xff1a; 例子代码 <!DOCTYPE html> <html lang"en"> <head><meta charset"UTF-8"><meta name"viewport&q…
阅读更多...
【HarmonyOS 4.0 应用开发实战】ArkTS 快速入门之常用属性

【HarmonyOS 4.0 应用开发实战】ArkTS 快速入门之常用属性

个人名片&#xff1a; &#x1f43c;作者简介&#xff1a;一名大三在校生&#xff0c;喜欢AI编程&#x1f38b; &#x1f43b;‍❄️个人主页&#x1f947;&#xff1a;落798. &#x1f43c;个人WeChat&#xff1a;hmmwx53 &#x1f54a;️系列专栏&#xff1a;&#x1f5bc;️…
阅读更多...
《统计学简易速速上手小册》第5章：回归分析（2024 最新版）

《统计学简易速速上手小册》第5章：回归分析（2024 最新版）

文章目录 5.1 线性回归基础5.1.1 基础知识5.1.2 主要案例&#xff1a;员工薪资预测5.1.3 拓展案例 1&#xff1a;广告支出与销售额关系5.1.4 拓展案例 2&#xff1a;房价与多个因素的关系 5.2 多元回归分析5.2.1 基础知识5.2.2 主要案例&#xff1a;企业收益与多因素关系分析5.…
阅读更多...
【小沐学GIS】基于WebGL绘制三维数字地球Earth（OpenGL）

【小沐学GIS】基于WebGL绘制三维数字地球Earth（OpenGL）

&#x1f37a;三维数字地球系列相关文章如下&#x1f37a;&#xff1a;1【小沐学GIS】基于C绘制三维数字地球Earth&#xff08;OpenGL、glfw、glut&#xff09;第一期2【小沐学GIS】基于C绘制三维数字地球Earth&#xff08;OpenGL、glfw、glut&#xff09;第二期3【小沐学GIS】…
阅读更多...
最短路径算法

最短路径算法

1. Dijkstra算法 在正数权重的有向图中求解某个源点到其余各个顶点的最短路径一般可以采用迪杰斯特拉算法&#xff08;Dijkstra算法&#xff09;。 1.1 适用场景 单源最短路径权重都为正 1.2 伪代码 1.3 示例 问题描述&#xff1a; 计算节点0到节点4的最短路径&#xff0c…
阅读更多...
arduino uno R3驱动直流减速电机（蓝牙控制）

arduino uno R3驱动直流减速电机（蓝牙控制）

此篇博客用于记录使用arduino驱动直流减速电机的过程&#xff0c;仅实现简单的功能&#xff1a;PID调速、蓝牙控制 1、直流减速电机简介2、DRV8833电机驱动模块简介3、HC-05蓝牙模块简介电机转动测试4、PID控制5、蓝牙控制电机 1、直流减速电机简介 我在淘宝购买的电机&#x…
阅读更多...
C语言整型数据类型..

C语言整型数据类型..

1.整型数据类型 在C语言中 根据数据范围从小到大依次为char、short、int、long、long long 但是对于整型来说 为什么有这么多类型呢 我们得先说字节的本质&#xff1a; 计算机是通过晶体管的开关状态来记录数据 晶体管通常8个为一组 称为一个字节 而晶体管由两种状态 分别是开…
阅读更多...
交叉熵损失函数（Cross-Entropy Loss）的基本概念与程序代码

交叉熵损失函数（Cross-Entropy Loss）的基本概念与程序代码

交叉熵损失函数&#xff08;Cross-Entropy Loss&#xff09;是机器学习和深度学习中常用的损失函数之一&#xff0c;用于分类问题。其基本概念如下&#xff1a; 1. 基本解释&#xff1a; 交叉熵损失函数衡量了模型预测的概率分布与真实概率分布之间的差异。在分类问题中&…
阅读更多...
春节假期：思考新一年的发展思路

春节假期：思考新一年的发展思路

春节假期是人们放松身心、享受家庭团聚的时刻&#xff0c;但除了走亲戚、玩、吃之外&#xff0c;我们确实也需要思考新的一年的发展思路。以下是一些建议&#xff0c;帮助您在春节假期中为新的一年做好准备&#xff1a; 回顾过去&#xff0c;总结经验&#xff1a;在春节期间&a…
阅读更多...
大华智慧园区综合管理平台/emap/devicePoint RCE漏洞

大华智慧园区综合管理平台/emap/devicePoint RCE漏洞

免责声明&#xff1a;文章来源互联网收集整理&#xff0c;请勿利用文章内的相关技术从事非法测试&#xff0c;由于传播、利用此文所提供的信息或者工具而造成的任何直接或者间接的后果及损失&#xff0c;均由使用者本人负责&#xff0c;所产生的一切不良后果与文章作者无关。该…
阅读更多...
【十六】【C++】stack的常见用法和练习

【十六】【C++】stack的常见用法和练习

stack的常见用法 C标准库中的stack是一种容器适配器&#xff0c;它提供了后进先出&#xff08;Last In First Out, LIFO&#xff09;的数据结构。stack使用一个底层容器进行封装&#xff0c;如deque、vector或list&#xff0c;但只允许从一端&#xff08;顶部&#xff09;进行…
阅读更多...
一周学会Django5 Python Web开发-Django5操作命令

一周学会Django5 Python Web开发-Django5操作命令

锋哥原创的Python Web开发 Django5视频教程&#xff1a; 2024版 Django5 Python web开发 视频教程(无废话版) 玩命更新中~_哔哩哔哩_bilibili2024版 Django5 Python web开发 视频教程(无废话版) 玩命更新中~共计11条视频&#xff0c;包括&#xff1a;2024版 Django5 Python we…
阅读更多...
第8讲个人中心页面搭建实现

第8讲个人中心页面搭建实现

个人中心页面搭建实现 <template><view class"user_center"><!-- 用户信息开始 --><view class"user_info_wrap"><!--获取头像--><button class"user_image"></button> <view class"user_n…
阅读更多...
14.盔甲？装甲？装饰者模式！

14.盔甲？装甲？装饰者模式！

人类的军工发展史就是一场矛与盾的追逐&#xff0c;矛利则盾坚&#xff0c;盾愈坚则矛愈利。在传统的冶金工艺下&#xff0c;更坚固的盾牌和盔甲往往意味着更迟缓笨重的运动能力和更高昂的移动成本。从战国末期的魏武卒、秦锐士&#xff0c;到两宋之交的铁浮图、重步兵&#xf…
阅读更多...
Roop的安装教程

Roop的安装教程

roop插件的安装&#xff0c;并不容易 并且最好就是在电脑本地完成&#xff0c;因为涉及到C、visual studio软件&#xff0c;并且还需要在电脑本地放置一些模型&#xff0c;用autoDL其实也有镜像&#xff0c;但是需要数据扩容至少100G&#xff0c;烧钱。。。 电脑本地&#xff0…
阅读更多...
javaweb物业管理系统jsp项目

javaweb物业管理系统jsp项目

文章目录 物业管理系统一、系统演示二、项目介绍三、系统部分功能截图四、部分代码展示五、底部获取项目源码&#xff08;9.9&#xffe5;带走&#xff09; 物业管理系统 可用作javaweb项目、servlet项目、jsp项目的项目设计 一、系统演示 物业管理系统 二、项目介绍 语言&a…
阅读更多...
ChatGPT高效提问—prompt常见用法（续篇）

ChatGPT高效提问—prompt常见用法（续篇）

ChatGPT高效提问—prompt常见用法&#xff08;续篇&#xff09; ​ 对话式prompt适用于模拟各种交流情境。若我们意图探索在特殊场合下可能出现的对话情景&#xff0c;或者模拟一段对话流程&#xff0c;可以采用这种方法&#xff0c;通过精准的prompt指令&#xff0c;引导Chat…
阅读更多...
多视图特征学习 Multi-view Feature Learning既可以被看作是一种学习框架，也可以被看作是一种具体的学习算法！

多视图特征学习 Multi-view Feature Learning既可以被看作是一种学习框架，也可以被看作是一种具体的学习算法！

Multi-view Feature Learning 1.多视图特征学习Multi-view Feature Learning的基本介绍总结 1.多视图特征学习Multi-view Feature Learning的基本介绍 多视图特征学习是一种利用多视图数据集来进行联合学习的机器学习方法。多视图数据指的是对同一事物从多种不同的途径或角度进…
阅读更多...
监测Nginx访问日志502情况后并做相应动作

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

今天带大家写一个比较实用的脚本哈 原理&#xff1a; 假设服务器环境为lnmp&#xff0c;近期访问经常出现502现象&#xff0c;且502错误在重启php-fpm服务后消失&#xff0c;因此需要编写监控脚本&#xff0c;一旦出现502&#xff0c;则自动重启php-fpm服务 场景&#xff1a; 1…
阅读更多...
人脸追踪案例及机器学习认识

人脸追踪案例及机器学习认识

1.人脸追踪机器人初制 用程序控制舵机运动的方法与机械臂项目完全相同。 由于摄像头的安装方式为上下倒转安装&#xff0c;我们在编写程序读取图像时需使用 flip 函数将 图像上下翻转。 现在&#xff0c;只需要使用哈尔特征检测得到人脸在图像中的位置&#xff0c;再指示舵机运…
阅读更多...
最新文章

Copyright @ 2022~2023