Semantic-Driven OpenAPI Generator for Go

22 Feb, 2026

Recently, I built a semantic-aware OpenAPI generator that extracts API definitions directly from Go code using the AST and type system.

Repository: https://github.com/arsfy/gswr

Background

Honestly, I’ve always felt that the Go ecosystem has been missing a tool in this space. In most cases, developers are forced to choose between:

• adopting a Protobuf-style ecosystem, or
• writing extensive annotations and relying on Swagger generators.

Both approaches introduce friction:

• Existing projects often require refactoring
• Large amounts of comments must be maintained
• Any logic change requires synchronized documentation updates

Even in the post-AI era—where AI can help automate documentation—this mainly reduces the time cost, rather than solving the underlying workflow problem.

Why I Built This Tool

This project was designed to handle complex real-world scenarios automatically, including:

1. Route Discovery

Supports nested Group(...) recursion and cross-file router chaining:

v1 := e.Group("v1")
UserRoute(v1.Group("user"))

func UserRoute(e *echo.Group) {
    e.GET("/list")
}

2. Complex Data Structures

Correctly analyzes constants, nested types, channels, external aliases, and more:

c := "ok"
v := <-ch

return c.JSON(200, types.Response{
    Code: c,
    Data: gin.H{
        "number": utils.GetRandomNumber(),
        "v": v,
    }
})

3. Input / Output Type Inference

Infers request and response types—even when wrapped or abstracted:

name := c.FormValue("name")
age := resp.GetInt(c, "age", 0)

return resp.Success("ok")

Current Status

More capabilities are described in the README. However:

• Test coverage is still limited
• Currently supports only Echo and Gin
• Has not yet been deployed widely in production environments

#Golang #Tools