Swagger

Swagger 是一组规范和工具,用于设计、构建、文档化和消费 RESTful 风格的 Web 服务。它旨在帮助开发者更轻松地设计和使用 API。

主要组成部分:

  1. OpenAPI 规范(以前称为 Swagger 规范): 定义了 API 的结构和功能,包括端点、参数、请求和响应格式等。使用 YAML 或 JSON 格式编写,描述了整个 API 的元数据。

  2. Swagger Editor: 提供了一个交互式的编辑器,用于创建和编辑 OpenAPI 规范。

  3. Swagger UI: 一个交互式的用户界面,用于可视化和交互式测试 API。通过 OpenAPI 规范生成交互式文档,开发者可以通过 Swagger UI 浏览 API 的端点、参数和响应,甚至可以在其中进行测试。

  4. 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

 

posted @   看一百次夜空里的深蓝  阅读(62)  评论(0编辑  收藏  举报
相关博文:
阅读排行:
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 我与微信审核的“相爱相杀”看个人小程序副业
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· spring官宣接入deepseek,真的太香了~
点击右上角即可分享
微信分享提示