Golang OpenAPI规范生成工具

最近在做一个Golang项目，需要生成OpenAPI规范文档。不知道大家有没有推荐的Golang OpenAPI规范生成工具？最好能支持以下特性：

  1. 自动从代码注释生成OpenAPI文档
  2. 支持Swagger UI集成
  3. 能够保持API文档与代码同步更新

目前了解到了swag和go-swagger，但不太确定哪个更适合。有没有实际使用过的朋友可以分享一下经验？或者有其他更好的工具推荐？

2 回复

推荐几个Golang OpenAPI规范生成工具：

  1. swaggo/swag：最流行，支持Swagger 2.0，集成Gin/Echo等框架。
  2. go-swagger：功能强大，支持代码生成和验证。
  3. deepmap/oapi-codegen：根据OpenAPI 3.0规范生成类型安全代码。
  4. getkin/kin-openapi：提供OpenAPI 3.0解析和验证库。

建议根据项目需求选择，swaggo适合快速集成，oapi-codegen适合类型安全要求高的场景。

更多关于Golang OpenAPI规范生成工具的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


在Golang中，有几个流行的工具可用于根据代码生成OpenAPI规范（Swagger文档），或从OpenAPI规范生成Golang代码。以下是主要推荐：

1. swaggo/swag

  • 用途：从Go代码注释自动生成OpenAPI 3.0规范。
  • 集成：与Gin、Echo等框架兼容。
  • 步骤：
    1. 使用注释标记路由和处理函数（如// @Summary）。
    2. 安装工具：go install github.com/swaggo/swag/cmd/swag@latest。
    3. 运行swag init生成swagger.json和swagger.yaml。
  • 示例注释：
    // @Summary 获取用户信息
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} User
// @Router /user/{id} [get]
func GetUser(c *gin.Context) { ... }

2. deepmap/oapi-codegen

  • 用途：从OpenAPI规范生成类型安全的Go服务器/客户端代码。
  • 步骤：
    1. 编写OpenAPI YAML/JSON文件。
    2. 生成代码：oapi-codegen -package myapi spec.yaml > myapi.gen.go。
  • 优势：确保代码与API设计一致，减少手动错误。

3. go-swagger/go-swagger

  • 功能：支持生成规范或代码，并提供验证等功能。
  • 用法：
    • 生成规范：通过注释或扫描代码。
    • 生成服务器：swagger generate server -f spec.yaml。

选择建议：

  • 快速文档化现有代码：用swaggo添加注释生成。
  • 设计优先：用oapi-codegen从规范生成类型安全代码。
  • 复杂API管理：go-swagger提供完整工具链。

根据项目需求选择合适工具，通常swaggo因简单易用而受欢迎。

回到顶部