Swagger
Swagger 是一组规范和工具,用于设计、构建、文档化和消费 RESTful 风格的 Web 服务。它旨在帮助开发者更轻松地设计和使用 API。
主要组成部分:
-
OpenAPI 规范(以前称为 Swagger 规范): 定义了 API 的结构和功能,包括端点、参数、请求和响应格式等。使用 YAML 或 JSON 格式编写,描述了整个 API 的元数据。
-
Swagger Editor: 提供了一个交互式的编辑器,用于创建和编辑 OpenAPI 规范。
-
Swagger UI: 一个交互式的用户界面,用于可视化和交互式测试 API。通过 OpenAPI 规范生成交互式文档,开发者可以通过 Swagger UI 浏览 API 的端点、参数和响应,甚至可以在其中进行测试。
-
Swagger Codegen: 根据 OpenAPI 规范自动生成 API 客户端库、服务器端框架和文档。
优势和功能:
-
文档化和可视化: 自动生成可交互的 API 文档,开发者可以直观地了解 API 的端点、参数和用法。
-
代码自动生成: 基于规范,自动生成客户端和服务器端代码,减少了开发工作量和潜在的错误。
-
易于测试和调试: Swagger UI 提供了一个交互式的界面,可以直接在其中测试 API,方便调试和验证功能。
-
标准化API设计: 规范的使用有助于标准化和约定 API 设计,使不同团队和开发者更容易理解和集成。
-
社区和生态系统支持: 拥有庞大的开发者社区和生态系统支持,使得整个工具集不断演进和改进。
Swagger 提供了一整套工具,帮助开发者更轻松地设计、构建和使用 API。它有助于提高 API 的可理解性、可靠性,并能够更好地支持不同团队之间的协作。
1 gin-swagger 嵌入到Gin框架中,通过注释的方式自动生成swagger.json文档 2 # 1. 源码下载 3 go get -u github.com/swaggo/swag/cmd/swag 4 # 2. 安装 5 go install github.com/swaggo/swag/cmd/swag@latest 6 # 3.初始化(安装好了就可以用了,每次修改api注释就得重新初始化就会重新生成文档) 7 swag init 8 # 4. 如果找不到命令就检查一下环境变量 9 export PATH=$GOROOT/bin:$PATH:$GOPATH/bin 10 # 5. 如果你有复杂的潜逃目录就需要指定-o 指定生成json的路径 11 swag init -g ./cmd/ginsimple/main.go -o cmd/docs 12 # 6.安装可视化web包 13 go get -u github.com/swaggo/gin-swagger 14 go get -u github.com/swaggo/files 15 # 7.可以直接开始用拉 16 package main 17 18 import ( 19 "github.com/gin-gonic/gin" 20 docs "demo/docs" // 这里是你swag生成的docs模块 21 swaggerfiles "github.com/swaggo/files" 22 ginSwagger "github.com/swaggo/gin-swagger" 23 "net/http" 24 ) 25 // @BasePath /api/v1 26 27 // PingExample godoc 28 // @Summary ping example 29 // @Schemes 30 // @Description do ping 31 // @Tags example 32 // @Accept json 33 // @Produce json 34 // @Success 200 {string} Helloworld 35 // @Router /example/helloworld [get] 36 func Helloworld(g *gin.Context) { 37 g.JSON(http.StatusOK,"helloworld") 38 } 39 40 func main() { 41 r := gin.Default() 42 docs.SwaggerInfo.BasePath = "/api/v1" 43 v1 := r.Group("/api/v1") 44 { 45 eg := v1.Group("/example") 46 { 47 eg.GET("/helloworld",Helloworld) 48 } 49 } 50 r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler)) 51 r.Run(":8080") 52 53 }
访问:http://localhost:8080/swagger/index.html 就可以看到自动生成的url api文档了
1 # 如果你只是需要加载生成OpenAIP规则 2 # 也就是生成的json文件,并不需要部署在本地(r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))) 3 # 你可以将OpenAPI部署到docker容器中去 4 docker pull swaggerapi/swagger-ui 5 docker run -p 4567:8080 -v /your_project/docs/swagger.json:/app/swagger.json -d -it swaggerapi/swagger-ui 6 http://localhost:4567
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 我与微信审核的“相爱相杀”看个人小程序副业
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· spring官宣接入deepseek,真的太香了~