How GinDoc Turns Go Code into Swagger Docs and Test Models

In API testing, model classes generated from interface definitions are crucial for request construction, response deserialization, and verification. However, development and test code often use different languages, making it hard to share model definitions directly.

Code‑First vs Doc‑First

Two strategies are described:

Code‑first : Write API code first, then generate documentation (e.g., using Swagger annotations). This approach relies on developers adding specific comment formats and running a Swagger CLI in CI/CD to produce the spec.

Doc‑first : Write an interface definition language (IDL) document first (e.g., Thrift), then generate code from it. This reuses existing IDL tooling but may require extra effort for large existing APIs.

Introducing GinDoc

GinDoc is a Go library built on the Gin HTTP framework that generates Swagger documentation and client code directly from route definitions, eliminating the need for separate annotations. It works by wrapping gin.IRouter with a doc object that provides methods such as Desc, Query, and Out to describe each endpoint.

Installation

go get github.com/yourorg/gindoc

Basic Usage

Original handler registration:

func (h AuditHandler) Register(r *ginex.Engine) {
    group := r.Group("/api/v1/audit")
    group.GET("/Search", SearchRecordList)
    group.GET("/GetResource", GetResourceTagList)
}

After adding GinDoc annotations:

func (h AuditHandler) Register(r *ginex.Engine) {
    group := doc.Group("/api/v1/audit").Desc("Audit Management")
    group.GET("/Search", SearchRecordList).
        Desc("Search").Query(dto.SearchAuditRecordReq{}).Out(dto.SearchAuditRecordResp{})
    group.GET("/GetResourceTagList", GetResourceTagList).
        Desc("Get Resource Tag List").Out(dto.GetResourceTagListResp{})
}

Model fields can be documented with desc tags and example values with ex tags:

type Student struct {
    Name string `json:"name" desc:"Name" ex:"Zhang San"`
    Age  int    `json:"age"  desc:"Age"  ex:"28"`
}

Generating a Swagger Server

At the application entry point, add a Swagger server route:

sw := swagger.Swagger{}
sw.ServeDoc(doc, "/swagger")

When the Go service starts, a Swagger UI is automatically served, allowing developers to view and download the generated API definition.

Generating Test Model Code

With the Swagger JSON file, test model classes can be generated using swagger-codegen:

swagger-codegen generate -i sample.json -l python -o sample_model

The resulting code can be used in automated test pipelines.

Advanced Topics

Multiple codebases / branches : Different domains or URL paths can expose distinct Swagger docs for separate services or branches.

Automatic synchronization : In CI pipelines, the test suite can check for updated Swagger specs, regenerate model classes, and run tests. Successful tests can be merged automatically; failures indicate potential breaking changes that need manual review.

Notes

GinDoc is currently an internal tool at ByteDance and not open‑source, but the underlying concept—generating documentation and test models directly from code—can be applied to other languages and frameworks.