在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 https://github.com/swagger-api/swagger-ui/archive/v3.31.1.tar.gz -o swagger-ui.tar.gz tar -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。
