Swagger/OpenAPI 生成用于 Go (Golang)：go-swagger 和 oapi-codegen

Swagger/OpenAPI 生成用于 Go (Golang)：go-swagger 和 oapi-codegen

在 Go 上开发现代 Web 服务需要严格的 API 规范。OpenAPI（以前称为 Swagger）是描述 RESTful 接口的标准，它允许自动创建客户端、服务器和文档。在 Go 生态系统中，有两个关键工具用于从 OpenAPI 规范生成代码：go-swagger 和 oapi-codegen。在本文中，我们将详细分析这两种方法、它们的安装和实际应用。

什么是 OpenAPI，为什么要生成代码？

OpenAPI 规范 (OAS) 是一种文件格式（通常是 YAML 或 JSON），用于描述 API 的端点、参数、数据类型和响应模式。您无需手动编写处理程序、模型和验证，而是可以：

• 生成包含路由和中间件的服务器端代码。
• 为其他服务生成客户端 SDK。
• 自动更新文档（Swagger UI）。
• 避免规范与实现之间的不同步。

工具 #1：go-swagger

go-swagger 是一个功能强大但更重量级的工具，它不仅支持生成，还支持规范验证。它非常适合具有版本控制的复杂项目。

安装 go-swagger

# 通过 go install 安装 (Go 1.17+)go install github.com/go-swagger/go-swagger/cmd/swagger@latest

# 检查安装swagger version

从规范生成服务器

假设我们有一个文件 api.yaml：

openapi: "3.0.0"info:  title: Pet Store  version: "1.0.0"paths:  /pets:    get:      summary: List all pets      operationId: listPets      responses:        '200':          description: A list of pets          content:            application/json:              schema:                type: array                items:                  $ref: '#/components/schemas/Pet'components:  schemas:    Pet:      type: object      properties:        id:          type: integer        name:          type: string

执行服务器生成：

swagger generate server -f api.yaml -A petstore -t ./gen

执行后，在 ./gen 文件夹中将出现：

• restapi/ — 处理程序和路由。
• models/ — 数据结构（Pet, Error 等）。
• cmd/ — 应用程序入口点。

处理程序实现示例

package restapi

import (    "net/http"    "petstore/gen/models"    "petstore/gen/restapi/operations")

func configureAPI(api *operations.PetstoreAPI) http.Handler {    api.ListPetsHandler = operations.ListPetsHandlerFunc(        func(params operations.ListPetsParams) middleware.Responder {            pets := []*models.Pet{                {ID: 1, Name: "Buddy"},                {ID: 2, Name: "Milo"},            }            return operations.NewListPetsOK().WithPayload(pets)        },    )    return api.Serve(nil)}

工具 #2：oapi-codegen

oapi-codegen 是来自 DeepMap 团队的现代、轻量且非常快速的生成器。它支持 OpenAPI 3.0 并专注于极简主义。推荐用于新项目。

安装 oapi-codegen

go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest

生成类型和服务器

使用相同的规范 api.yaml。执行：

oapi-codegen -generate types,server -package petstore api.yaml > petstore.gen.go

标志 -generate 允许您选择生成的内容：

• types — Go 结构