Hertz 整合swagger

文章目录

    • Swagger
      • 安装
      • 使用用法
      • 项目demo
      • Swagger注释用法
        • 通用API信息
      • swag命令行参数
      • swagger路由配置

Swagger

安装

go get 安装可执行文件需要配合 GOPATH 模式工作。
go get github.com/swaggo/swag/cmd/swag
因为从 Go 1.17 开始,在 go mod 模式下通过 go get 下载对应库文件将无法自动编译并安装到 $GOPATH/bin 的路径, 所以不再推荐用 go get 来安装可执行文件的方式。可以使用 go install来代替。

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

使用用法

  1. 在你的 API 源代码中添加注释。
  2. 在你的 Go 项目的根目录下运行 Swag (例如 ~/root/go-project-name),Swag 会解析注释并在 ~/root/go-project-name/docs 目录下生成必要的文件 (docs 文件夹和 docs/doc.go)。
    swag init
  3. 通过运行以下命令在工程中下载 hertz-swagger :
go get github.com/hertz-contrib/swagger
go get github.com/swaggo/files

并在你的代码中引用如下代码:

import "github.com/hertz-contrib/swagger" // hertz-swagger middleware
import "github.com/swaggo/files" // swagger embed files

效果
在这里插入图片描述

项目demo

使用过程
使用 hertz-swagger 规则为 api 和主函数添加注释,如下所示:
使用 swag init 命令来生成文档,生成的文档将被存储在docs/目录下。
编译运行你的应用程序,之后在 http://localhost:8888/swagger/index.html,可以看到 Swagger UI 界面。

完整代码

package mainimport ("context""github.com/cloudwego/hertz/pkg/app""github.com/cloudwego/hertz/pkg/app/server""github.com/hertz-contrib/swagger"_ "mystudy/docs" //该项一定要配置,否则会出现访问404swaggerFiles "github.com/swaggo/files"
)// PingHandler 测试 handler
// @Summary 测试 Summary
// @Description 测试 Description
// @Accept application/json
// @Produce application/json
// @Router /ping [get]
func PingHandler(c context.Context, ctx *app.RequestContext) {ctx.JSON(200, map[string]string{"ping": "pong",})
}// @title HertzTest
// @version 1.0
// @description This is a demo using Hertz.// @contact.name hertz-contrib
// @contact.url https://github.com/onewcode// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host localhost:8888
// @BasePath /
// @schemes http
func main() {h := server.Default()h.GET("/ping", PingHandler)url := swagger.URL("http://localhost:8888/swagger/doc.json") // The url pointing to API definitionh.GET("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler, url))h.Spin()
}

访问http://localhost:8888/swagger/index.html

效果
在这里插入图片描述

Swagger注释用法

通用API信息

示例 celler/main.go

注释说明示例
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.url https://example.com
tag.docs.description标签的外部文档说明。// @tag.docs.description Best example documentation
termsOfServiceAPI的服务条款。// @termsOfService http://swagger.io/terms/
contact.name公开的API的联系信息。// @contact.name API Support
contact.url联系信息的URL。 必须采用网址格式。// @contact.url http://www.swagger.io/support
contact.email联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。// @contact.email support@swagger.io
license.name必填 用于API的许可证名称。// @license.name Apache 2.0
license.url用于API的许可证的URL。 必须采用网址格式。// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
host运行API的主机(主机名或IP地址)。// @host localhost:8080
BasePath运行API的基本路径。// @BasePath /api/v1

更多请参考 https://github.com/swaggo/swag/blob/master/README_zh-CN.md

swag命令行参数

用参数运行 Swag (全部参数可以通过运行 swag init -h 查看)。

swag init --parseDependency --parseInternal --parseDepth 5 --instanceName "swagger"
选项默认值描述
parseInternalfalse解析内部依赖包。
parseDependencyfalse解析外部依赖包。
parseDepth100解析依赖包深度,如果你知道解析结构的深度,推荐使用这个参数,swag 命令的执行时间会显著减少。
instanceName“swagger”swagger 文档的实例名称。如果要在一个 Hertz 路由上部署多个不同的 swagger 实例,请确保每个实例有一个唯一的名字。

swagger路由配置

你可以使用不同的配置选项来配置 Swagger。

func main() {h := server.Default()h.GET("/ping", PingHandler)url := swagger.URL("http://localhost:8888/swagger/doc.json") // The url pointing to API definitionh.GET("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler, url, swagger.DefaultModelsExpandDepth(-1)))h.Spin()
}
选项类型默认值描述
URLstring“doc.json”指向 API 定义的 URL
DocExpansionstring“list”控制操作和标签的默认扩展设置。它可以是 list(只展开标签)、full(展开标签和操作)或 none(不展开)。
DeepLinkingbooltrue如果设置为 true,可以启用标签和操作的深度链接。更多信息请参见深度链接文档。
DefaultModelsExpandDepthint1模型的默认扩展深度(设置为 -1 完全隐藏模型)。
PersistAuthorizationboolfalse如果设置为 true,则会持久化保存授权数据,在浏览器关闭/刷新时不会丢失。
Oauth2DefaultClientIDstring“”如果设置了这个字段,它将用于预填 OAuth2 授权对话框的 client_id 字段。

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

如若内容造成侵权/违法违规/事实不符,请联系编程知识网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

Openwrt 启用未分配的硬盘空间

参考博客 利用剩余空间扩容根目录 启用未分配空间的过程简述 安装 cfdisk, openwrt -> 系统 -> 软件包 -> 搜索 cfdisk 实体机命令行或者网页端进行操作 cfdisk 命令进入磁盘分区界面,用键盘的上下方向键切换到 Free space (剩余…

CRM:如何通过客户数据分析获得业务洞察?

客户数据分析,也称客户分析,是收集、组织和分析客户数据,以深入了解客户行为的过程。企业将利用这些数据来制定与营销、产品开发、销售等相关的业务决策。 通过客户分析,你可以做出简单的业务决策,比如找出投资回报率…

MySQL字符函数

在数据库中,字符函数是一组用于处理字符串的函数。这些函数可以帮助我们执行各种操作,如连接、比较、替换等。本文将介绍一些常用的MySQL字符函数,并演示如何在查询中使用它们。 1.concat() 函数 CONCAT() 函数用于连接两个或多个字符串。它…

locked1勒索病毒,刚攻击完海康威视系统,又再针对速达软件服务器攻击

导言: .locked、.locked1勒索病毒正成为数字安全的一大威胁。本文91数据恢复将深入介绍.locked、.locked1勒索病毒的特点、如何有效恢复被其加密的数据文件,以及预防这一数字噩梦的方法。如果您正在经历勒索病毒数据恢复的困境,我们愿意与您…

【算法】单调栈题单——字典序最小⭐(一种类型的模板题)

文章目录 题目列表316. 去除重复字母⭐⭐⭐⭐⭐(类型题模板:单调栈,字典序最小)221021天池-03. 整理书架(保留数量为 limit 的字典序最小)402. 移掉 K 位数字(最多删除 k 次 前导零的处理&…

41 - 如何使用缓存优化系统性能?

缓存是我们提高系统性能的一项必不可少的技术,无论是前端、还是后端,都应用到了缓存技术。前端使用缓存,可以降低多次请求服务的压力;后端使用缓存,可以降低数据库操作的压力,提升读取数据的性能。 今天我…

Python-docx 深入word源码 自定义页码页脚以动态显示总页数和当前页数

代码和效果图 先上能够正常显示页码页脚的Python代码和效果图,之后再解释原理和思路 from docx import Document from docx.shared import Pt from docx.oxml import OxmlElement from docx.enum.text import WD_PARAGRAPH_ALIGNMENT from docx.oxml.ns import qn…

【报名】2023产业区块链生态日暨 FISCO BCOS 开源六周年生态大会

作为2023深圳国际金融科技节系列活动之一,由深圳市地方金融监督管理局指导,微众银行、金链盟主办的“2023产业区块链生态日暨FISCO BCOS开源六周年生态大会”将于12月15日下午14:00在深圳举办。 今年的盛会将进一步升级,以“FISCO BCOS和TA的…

微软 Power Platform 零基础 Power Pages 网页搭建教程学习实践进阶以及常见问题解答(二)

微软 Power Platform 零基础 Power Pages 网页搭建教程学习实践进阶及常见问题解答(二) Power Pages 学习实践进阶 微软 Power Platform 零基础 Power Pages 网页搭建教程学习实践进阶及常见问题解答(二)Power Pages 核心工具和组…

Windows server 2016 FTP服务器的搭建

FTP(File Transfer Protocol)是一个用来在两台计算机之间传输文件的通信协议。这两台计算机中,一台是FTP服务器,另一台是FTP 客户端。 1.安装FTP服务与建立FTP站点 1.1 打开服务器管理器——单击仪表盘的添加角色和功能 1.2 持续…

玩转大数据4:大数据的崛起与应用领域探索

图片来源网络 引言 在当今数字化时代,大数据正以前所未有的速度和规模崛起。大数据的出现不仅改变了企业和组织的经营模式,也对我们的社会生活带来了深刻的影响。Java作为一种广泛使用的编程语言,在大数据领域发挥着重要的作用。本文将重点…

CGAL的四叉树、八叉树、正交树

四叉树(Quadtree):四叉树是一种用于二维空间分割的数据结构。它将一个二维区域划分为四个象限,每个象限进一步细分为四个小块,以此类推。四叉树可以用于空间索引、图形学、地理信息系统(GIS)等领…