Gin+Swagger快速生成API文档
发布网友
发布时间：2024-09-26 19:23
共1个回答
热心网友
时间：2024-11-22 04:47
在restful前后端项目进行接口对接的时候，需要有明确的接口文档，此时单独针对接口编写接口文档，耗时耗力，切代码修改后，还需要维护接口文档，此时容易出现文档不统一的情况，将接口文档直接写在代码中是一种比较好的方式。
swagger就是解决这种问题，开发人员只需要按照特定规范在编写接口代码时写上swagger注释，利用swagger生成接口文档。
二.SwaggerUI简介Swagger是一个API生成工具，可以生成文档。Swagger是通过编写yaml和json来实现文档化。并且可以进行测试等工作。
通过swagger可以方便的生成接口文档，方便前端进行查看和测试。
三.项目集成3.1安装swag$gogetgithub.com/swaggo/swag/cmd/swag3.2生成文件首次生成相关文件，后期代码修改过，添加swag注解后，也需要
#在go项目中（包含main.go）的目录，使用swaginit命令生成相关文件。$swaginit2021/09/2316:32:23Generateswaggerdocs....2021/09/2316:32:23GenerategeneralAPIInfo,searchdir:./2021/09/2316:32:26createdocs.goatdocs/docs.go2021/09/2316:32:26createswagger.jsonatdocs/swagger.json2021/09/2316:32:26createswagger.yamlatdocs/swagger.yaml3.3安装gin-swagger$goget-ugithub.com/swaggo/gin-swagger$goget-ugithub.com/swaggo/gin-swagger/swaggerFiles3.4集成引入生成的docs包
在具体接口上根据规范swag编写接口描述
在路由中进行引入
再次执行swaginit更新接口
运行应用后，浏览器访问：http://localhost:8887/swagger/index.html
packagemainimport("github.com/gin-gonic/gin"swaggerFiles"github.com/swaggo/files"ginSwagger"github.com/swaggo/gin-swagger"_"github.com/swaggo/gin-swagger/example/basic/docs"//docsisgeneratedbySwagCLI,youhavetoimportit.)//@titleSwaggerExampleAPI//@version1.0//@descriptionThisisasampleserverPetstoreserver.//@termsOfServicehttp://swagger.io/terms///@contact.nameAPISupport//@contact.urlhttp://www.swagger.io/support//@contact.emailsupport@swagger.io//@license.nameApache2.0//@license.urlhttp://www.apache.org/licenses/LICENSE-2.0.html//@hostpetstore.swagger.io//@BasePath/v2funcmain(){r:=gin.New()url:=ginSwagger.URL("http://localhost:8080/swagger/doc.json")//TheurlpointingtoAPIdefinitionr.GET("/swagger/*any",ginSwagger.WrapHandler(swaggerFiles.Handler,url))r.Run()}例如json
//@Paramdatabodymodels.RegistryAuthtrue"请示参数data"4.2返回4.2.1字符串//@Success200{string}json"{"msg":"ok"}"4.2.2结构体返回//@Success200{object}models.Response"请求成功"//@Failure400{object}models.ResponseErr"请求错误"//@Failure500{object}models.ResponseErr"内部错误"五.实战5.1main函数添加全局//@titlesmartkm_api_imageSwaggerExample//@version1.0//@descriptionThisisasampleserverPetstoreserver.//@termsOfServicehttp://swagger.io/terms///@contact.nameAPISupport//@contact.urlhttp://www.swagger.io/support//@contact.emailsupport@swagger.io//@license.nameApache2.0//@license.urlhttp://www.apache.org/licenses/LICENSE-2.0.html//@hostpetstore.swagger.io//@BasePath/funcmain(){//启动服务run()}5.2函数级别5.2.1Get请求//@Summary查看迁移任务详细信息//@Description查看迁移任务详细信息//@Acceptjson//@Procejson//@Paramtask_idpathstringtrue"task_id"//@Success200{object}models.Response"请求成功"//@Failure400{object}models.ResponseErr"请求错误"//@Failure500{object}models.ResponseErr"内部错误"//@Router/task[get]5.2.2Post请求//@Summary创建镜像迁移任务//@Description创建镜像迁移任务//@Acceptjson//@Procejson//@Paramdatabodymodels.CreateTaskReqtrue"请示参数data"//@Success200{object}models.Response"请求成功"//@Failure400{object}models.ResponseErr"请求错误"//@Failure500{object}models.ResponseErr"内部错误"//@Router/task[post]5.2.3Delete请求//@Summary删除镜像迁移任务//@Description删除镜像迁移任务//@Acceptjson//@Procejson//@Paramdatabodymodels.TaskReqtrue"请示参数data"//@Success200{object}models.Response"请求成功"//@Failure400{object}models.ResponseErr"请求错误"//@Failure500{object}models.ResponseErr"内部错误"//@Router/task[delete]注意事项在路由添加swagger的时候，需要引入项目生成的docs包
假如func方法头标注的swagger注释不正确，在执行swaginit会报错，自行根据报错信息去修改；
访问swagger控制台报错404pagenotfound，是因为没有添加swagger的路由
访问swagger控制台报错Failedtoloadspec，是因为没有import引入执行swaginit生成的swagger的docs文件夹；
参考链接https://studygolang.com/articles/12354
https://github.com/go-swagger/go-swagger
https://github.com/swaggo/gin-swagger
