在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
