1.为什么后端要配置swagger
在前后端分离项目中,后端配置swagger可以更好的帮助前端人员了解后端接口参数和数据的传输。
Swagger是一个用于设计、构建和文档化API的开源框架。在Go语言中,Swagger可以帮助后端开发人员快速创建和定义RESTful API,并提供自动生成文档的功能,这些文档包含了API的详细信息以及如何使用它们的说明。
配置Swagger有以下几个好处:
-
文档化API:Swagger可以生成易于阅读和理解的API文档,使开发人员能够快速查看API的调用方式和参数要求。这有助于消除开发过程中的沟通障碍和误解,并提高API的可靠性和稳定性。
-
自动化测试:Swagger可以自动生成API的测试代码,这样可以大大减少手动编写测试代码的工作量,并且可以更容易地进行集成测试。
-
更好的API设计:通过使用Swagger,开发人员可以更好地规范API的设计,使得API更加清晰和易于使用,从而提高了API的质量和用户体验。
-
与其他系统的集成:Swagger支持多种格式和方法,可以轻松地与其他系统进行集成,例如Postman等常见的API测试和管理工具。
总之,在Go语言项目中配置Swagger有利于提高API的可靠性、可维护性和可扩展性,并且可以帮助开发人员更好地设计和管理API。
2.配置swagger的步骤
官方网址:如何与Gin集成-地鼠文档
1.下载相关依赖
打开goland的终端
下载依赖
go get -u github.com/swaggo/swag/cmd/swag
go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
验证swagger是否安装成功
2.给接口代码添加声明式注释
在主方法添加注释
添加swagger访问路由
注意:如果在这个地方遇到报错
解决办法:
1.先清除缓存
2.重新下载依赖
go get -u github.com/swaggo/files
在接口方法添加注释
3.初始化swagger
1.手动添加一条依赖,爆红先不管,接下来会解决
2.美化注释格式
3.初始化swagger
会生成一个docs目录以及三个文件夹
3.结果展示
启动项目之后,打开http://127.0.0.1:8080/swagger/index.html
4.注意(容易踩的雷):
每次添加或修改注解后,都需要使用swag init命令重新生成文档,使其生效
目前只注释了一个接口,在注释其他接口的时候,注意要初始化。
有关接口的注释详细信息看这里:通用API信息-地鼠文档