在Golang中使用SwaggerUI进行API在线文档自动化

在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文档。

步骤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。

以上是在Golang中使用SwaggerUI进行API在线文档自动化的详细内容。更多信息请关注PHP中文网其他相关文章！