Swagger/OpenAPI 生成工具 for Go (Golang)：完整指南

Swagger/OpenAPI 生成工具 for Go (Golang)

在使用 Go (Golang) 开发 Web 服务时，关键任务之一是创建高质量且最新的 API 文档。Swagger（现称为 OpenAPI）已成为描述 RESTful 接口的行业标准。在本文中，我们将介绍 Go 生态系统中用于生成 OpenAPI 规范的主要工具、它们的安装、配置和实际应用。

为什么 OpenAPI 对 Go 开发者很重要？

OpenAPI 允许您创建机器可读的 API 描述，可用于：

• 自动生成不同语言的客户端库
• 创建交互式文档（Swagger UI）
• 验证传入和传出的请求
• 使用 Postman 或 Insomnia 等工具测试 API

Go 中用于生成 OpenAPI 的主要库

1. swaggo/swag — 最流行的选择

swaggo/swag 库是 Go 中生成 Swagger 文档的事实标准。它基于代码注释中的注解工作。

安装：

go get -u github.com/swaggo/swag/cmd/swaggo get -u github.com/swaggo/gin-swagger  // 用于 Gin 框架go get -u github.com/swaggo/files

与 Gin 一起使用的示例：

package main

import (    "github.com/gin-gonic/gin"    "github.com/swaggo/gin-swagger"    "github.com/swaggo/files"    _ "your-module/docs" // 生成的包)

// @title           My API// @version         1.0// @description     使用 Swagger 的 Go API 示例// @host            localhost:8080// @BasePath        /api/v1

func main() {    r := gin.Default()        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))        r.GET("/api/v1/users", GetUsers)    r.Run(":8080")}

// GetUsers 返回用户列表// @Summary      获取用户列表// @Description  返回系统中的所有用户// @Tags         users// @Accept       json// @Produce      json// @Success      200  {array}   User// @Router       /users [get]func GetUsers(c *gin.Context) {    users := []User{{ID: 1, Name: "伊万"}}    c.JSON(200, users)}

type User struct {    ID   int    `json:"id" example:"1"`    Name string `json:"name" example:"伊万"`}

编写代码后，执行命令：

swag init

这将创建一个包含 swagger.json 和 swagger.yaml 文件的 docs 文件夹。

2. go-swagger — 功能强大但更复杂的工具

go-swagger 不仅提供从代码生成文档的功能，还提供反向过程——从规范生成代码。

安装：

go get -u github.com/go-swagger/go-swagger/cmd/swagger

从规范生成服务器的示例：

swagger generate server -f ./swagger.yaml -A my-api

从代码生成文档：

// swagger:route GET /users users listUsers// 返回用户列表。// responses://   200: usersResponse

func ListUsersHandler(w http.ResponseWriter, r *http.Request) {    // 实现}

3. oapi-codegen — 带有代码生成的现代方法

oapi-codegen 库允许基于 OpenAPI 规范生成类型、服务器存根和客户端。

安装：

go get -u github.com/deepmap/oapi-codegen/cmd/oapi-codegen

使用示例：

首先创建 api.yaml 文件：

openapi: "3.0.0"info:  title: My API  version: "1.0"paths:  /users:    get:      oper