在golang中使用swaggerui进行api在线文档自动化
API(应用程序编程接口)的使用已经成为现代应用程序开发中的必要元素。API让前后端分离、微服务和云应用变得更容易。 但是,一个好的API并不仅仅是实现了功能,而是对用户友好和易于使用。为此,文档化API变得越来越重要。在线文档的好处在于可以在操作API之前了解它。
在本文中,我们将介绍如何使用SwaggerUI记录API文档以及如何在Golang中自动化此过程,以便更轻松地维护,提供可读性好的文档,方便其他团队与合作伙伴了解您的API。
SwaggerUI是一个流行的工具,用于为API创建文档,生成交互式API文档,通过可视化方式描述API,可以生成人类可读的文档和机器可读的JSON或YAML。SwaggerUI可与许多编程语言集成,包括Golang。
首先,您需要使用SwaggerUI的Golang实现——Swag。Swag是一个自动化API文档化工具,结合了Go语言的注释和Swagger注释,可自动生成Swagger2.0文档。
立即学习“go语言免费学习笔记(深入)”;
步骤1:安装Swag
在终端/cmd中使用以下命令下载和安装Swag:
go get -u github.com/swaggo/swag/cmd/swag
登录后复制
步骤2:在代码中添加Swagger注释
在代码中添加Swagger注释以描述API。
在HTTP处理程序函数上方的注释中添加Swagger注释,例如:
// GetByID godoc// @Summary Get user details by ID// @Description Get user details by ID// @Tags user// @Accept json// @Produce json// @Param id path int true "User ID"// @Success 200 {object} model.User// @Failure 400 {object} ErrorResponse// @Router /users/{id} [get]func GetByID(c *gin.Context) { //…code here…}
登录后复制
步骤3:生成Swagger JSON文件
使用以下命令在代码库的根目录中生成Swagger JSON文件:
swag init
登录后复制
该命令将使用代码中的Swagger注释并生成Swagger JSON文件。也可以在项目的Makefile中添加它。
步骤4:集成SwaggerUI
Swag使用SwaggerUI作为浏览器中展示API文档的前端,我们需要将SwaggerUI中的文件静态反向代理到我们的应用程序中。
假设我们的Golang应用程序在端口8080上运行。我们将使用的SwaggerUI版本是v3.31.1。我们可以通过以下方式从官方SwaggerUI GitHub页面进行下载:
curl -L D:pic/2025-03-02/https://cdn.chuangxiangniao.com/2025/03/20250301233901288.gz -o swagger-ui.tar.gztar -xf swagger-ui.tar.gz
登录后复制
这将在本地目录中生成swagger-ui文件夹,其中包含SwaggerUI的所有文件。我们将使用nginx作为反向代理服务器(您可以使用Apache,Caddy等),在终端/cmd中使用以下命令启动nginx:
nginx -c /path/to/nginx.conf
登录后复制
在nginx.conf文件中,我们需要添加以下内容:
http { server { listen 8081; # 访问静态文件的端口 server_name _; root /path/to/swagger-ui/dist; location / { try_files $uri $uri/ @go; } location @go { proxy_redirect off; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://127.0.0.1:8080; # 代理请求的端口 } location /swagger-ui/ { try_files $uri $uri/ =404; } }}
登录后复制
在上述nginx配置中,我们将静态SwaggerUI文件夹/swagger-ui/dist目录添加到nginx服务器的根目录中作为静态文件,我们代理到localhost:8080(我们自己的应用程序)的所有请求通过转发到由8081端口监听的端口。我们通过访问http://localhost:8081/swagger-ui/来查看和使用SwaggerUI。
步骤5:查看API文档
在浏览器中访问http://localhost:8081/swagger-ui/,SwaggerUI应用程序将显示出现在根目录中的SwaggerUI static文件夹。您可以在该页面中找到所有文档好的API列表。单击要查看的API文档会在右侧显示。该网站提供直接在API上测试和查看API文档的API用户友好界面。这个过程中,GUI展示Swagger注释自动提取的的详细信息,比如提供了此api的参数,body信息,Api版本,api格式等等,这将大大节省您编写文档的时间和精力。
结论
API文档是API设计和开发过程的重要工具,因此我们需要在构建应用程序中考虑文档化API。利用自动化工具Swag,我们可以轻松地在Golang中进行API文档自动化。使用SwaggerUI作为可视化工具来查看和测试文档化的API也非常方便。这将为其他团队和协作伙伴提供帮助,并使他们更容易地了解我们的API。
以上就是在Golang中使用SwaggerUI进行API在线文档自动化的详细内容,更多请关注【创想鸟】其它相关文章!
版权声明:本文内容由互联网用户自发贡献,该文观点仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容, 请发送邮件至253000106@qq.com举报,一经查实,本站将立刻删除。
发布者:PHP中文网,转转请注明出处:https://www.chuangxiangniao.com/p/2385248.html