DEV Community: Tran Long An

Your Go struct already describes your API. Let it write the docs too.

Tran Long An — Sun, 07 Jun 2026 04:04:20 +0000

Your Go struct already describes your API. Let it write the docs too.

If you build HTTP APIs in Go, you've lived this: the same endpoint is described in
three different places, by hand, and all three have to agree.

The handler reads the body, pulls query params, parses headers — binding.
The validator checks the body is well-formed — required, email, ranges.
The OpenAPI doc tells clients what the endpoint expects and returns.

The code already knows all of this. The Go type for the request says exactly
which fields exist, what types they are, which are required. Yet the docs repeat
it in YAML, the validator repeats it in tags, and nothing keeps them in sync. You
rename a field, ship it, and the docs quietly lie until someone files a bug.

Multiply that by a few dozen routes, each wired slightly differently across
gin, chi, or net/http, and "the docs" become a second codebase you maintain
by discipline alone.

oapi removes two of those three places. You write the request and response
as typed Go structs once. Binding, validation, and the OpenAPI 3 document all read
the same struct tags — so the docs are generated from the exact types your
handler binds. They cannot drift, because there is nothing to keep in sync.

⭐ GitHub: github.com/antlss/oapi — go get github.com/antlss/oapi

The idea in one signature

Every handler has the same shape: a typed request in, a typed response out.

func(ctx context.Context, req oapi.Request[Header, Param, Query, Body]) (*Response, error)

Request[Header, Param, Query, Body] is the whole contract. Each part binds from
a different source, and you use struct{} for the parts an endpoint doesn't need:

Header -> `header:"..."`   Param -> `uri:"..."`
Query  -> `form:"..."`     Body  -> `json:"..."` (or `form:"..."` for multipart/urlencoded)

That's it. The handler receives data already parsed, validated, and typed. No
c.ShouldBindJSON(&x), no manual c.Param("id"), no if err != nil boilerplate
in every function.

What the type buys you

1. The type is the entire data model

Define the request once. The struct tags carry three readers at the same time:

type CreateProductBody struct {
    Name      string   `json:"name"      binding:"required,min=2,max=120"                   example:"Mechanical Keyboard"`
    SKU       string   `json:"sku"       binding:"required,uuid"                            example:"5f9c2e3a-1b4d-4c8e-9f0a-2b3c4d5e6f70"`
    Price     float64  `json:"price"     binding:"required,gt=0"                            example:"49.90"`
    Currency  string   `json:"currency"  binding:"required,oneof=USD EUR JPY VND"           example:"USD"`
    Category  string   `json:"category"  binding:"required,oneof=book electronics food toy" example:"electronics"`
    Website   string   `json:"website"   binding:"omitempty,url"                            example:"https://example.com"`
    Tags      []string `json:"tags"      binding:"omitempty,max=10"                         example:"new,featured"`
    Warehouse Address  `json:"warehouse"`
}

json:"name" — how the body decodes (binding).
binding:"required,min=2,max=120" — what makes it valid, and the schema constraints in the docs (required field, minLength/maxLength).
example:"..." — the sample value clients see in Swagger UI / Redoc.

Nested structs like Warehouse Address are recursed into — their rules and
examples reach the docs too. Rename Name, change min=2 to min=3, add a
field: the binding, the validation, and the published schema all move together,
because they are the same declaration.

2. The docs generate themselves — and stay honest

A Registry collects your routes and turns them into a validated OpenAPI 3
document (JSON or YAML). Because it reads the captured Go types, not a separate
spec file, the document describes exactly what the handler binds.

Here is the struct above, rendered with zero hand-written OpenAPI:

Notice what carried over automatically: category shows its oneof as an
enum, sku is documented as a uuid, name shows its [2..120] characters
bound, website as a url, tags as an array with <= 10 items, and the
request sample uses your real example values instead of bare "string"
placeholders. None of that was written by hand. It was read off the type.

3. Standardized requests and responses — across five frameworks

The same []Route runs unchanged on net/http, gin, Fiber v2,
chi, and Echo v4. The core is framework-agnostic; each adapter is a thin
seam. Pick a framework, or switch later, without rewriting a single handler.

Successful responses share one envelope by default — {"data": ...}, plus
{"meta": ...} for paginated endpoints — so every endpoint in your API answers
in a predictable shape, and clients can rely on it.

4. You still own the parts that are opinions

Standardization shouldn't mean a straitjacket. The things every project does
differently are pluggable seams, and the library ships no policy of its own:

Validation is an interface. The core depends on no validation library. Plug in go-playground/validator (a ready reference implementation is included), or your own.
The response envelope is swappable. Keep the default {"data": ...}, switch to {"success": true, "data": ...} for the whole API, override it per route, or return the raw model with no wrapper at all.
Error handling is yours. Return an HTTPError, map domain errors per route with an ErrorMapper, or install one process-wide ErrorParser that renders every error in your project's shape — and that shape gets documented too. Anything unrecognized renders a generic 500 and never leaks internals.

Crucially, every one of these seams drives both the bytes on the wire and
the generated docs. Customize the error shape, and the OpenAPI document describes
your custom error shape. No drift, even when you go off the defaults.

A complete API in a few lines

Define a handler over a typed request, declare the route with whatever
documentation metadata you want, and mount it.

func (h *Handler) createProduct() oapi.Route {
    return oapi.NewRichRoute(
        http.MethodPost, "/products",
        func(_ context.Context, req oapi.Request[struct{}, struct{}, struct{}, CreateProductBody]) (*oapi.Result, error) {
            p := h.catalog.CreateProduct(req.Body) // req.Body is already bound + validated
            return oapi.NewDataResult(p).
                WithStatus(http.StatusCreated).
                WithHeader("Location", fmt.Sprintf("/products/%d", p.ID)), nil
        },
        oapi.WithSummary("Create a product"),
        oapi.WithTags("catalog"),
        oapi.WithSuccessStatus(http.StatusCreated),
        oapi.WithResponseType[Product](),
        oapi.WithSecurity("bearerAuth", "products:write"),
        oapi.WithResponse[struct{}](http.StatusConflict, "Duplicate SKU"),
    )
}

Collect your routes into a Registry, add document-level metadata once, and you
have a self-describing API:

reg := oapi.NewRegistry("Catalog API", "v1").
    Describe("A demo API exercising typed binding, validation-driven docs, files, paging, security and the full error model.").
    AddServer("http://localhost:8080", "Local server").
    AddSecurityScheme("bearerAuth", oapi.BearerAuth()).
    AddTag("catalog", "Browse, create and manage products").
    Add(h.Routes()...)

Then wire it to a framework and serve the spec — here on gin:

oapi.SetValidator(validation.New()) // turn on validation; the core ships none

engine := gin.New()
ginadapter.RegisterAll(engine, h.Routes()...)
engine.GET("/openapi.json", ginadapter.SpecHandler(reg))
// serve Swagger UI / Redoc from the same spec...
engine.Run(":8080")

Or generate the spec to disk for CI, client codegen, or publishing:

reg.Write(context.Background(), oapi.GenConfig{Dir: "./openapi"}) // openapi.json + openapi.yaml

That's the whole loop: write the type, write the handler, get a validated API
and its documentation. The screenshots above are this exact code.

The point

Documentation drifts because it's a copy. The moment your API description lives in
a separate file maintained by hand, it starts aging the second you ship a change.

oapi makes the Go type the single source of truth. Binding reads it, validation
reads it, the OpenAPI document reads it — one declaration, three jobs, no copies to
keep in sync. You keep full control over the parts that are genuinely your call:
how you validate, how you shape responses, how you handle errors. The library just
makes sure that whatever you decide, the docs say the same thing your code does.

Write the struct. Ship the API. The docs are already correct.

oapi is open source (MIT), pre-1.0, and lives on GitHub:
github.com/antlss/oapi — stars, issues and PRs
are very welcome. Install with go get github.com/antlss/oapi. Five adapters:
net/http, gin, Fiber v2, chi, Echo v4. The runnable Catalog API that produced the
screenshots above lives in examples/ — go run ./examples/cmd/gin
and open http://localhost:8080.

I got tired of AI Reviewers hallucinating, so I built an Autonomous Agent for GitLab instead.

Tran Long An — Sun, 08 Mar 2026 06:00:34 +0000

We've all been there. You push a massive 300-line Merge Request, and within 3 seconds, an "AI Code Reviewer" bot leaves 12 comments on your PR.

You read them. Two comments complain about a "missing import" that is clearly handled globally by your framework. One suggests a library you explicitly removed last sprint. The rest are annoying formatting nits. You quietly click "Resolve Thread" 12 times and sigh.

Standard AI reviewers pipe your .patch file into an LLM and pray for the best. They lack context.

That’s exactly why I built AI Review Agent. A truly autonomous, context-aware code review agent built natively for GitLab using Go.

🧠 The Problem with "Dumb" AI Reviewers

When a human senior developer reviews a PR, they don’t just look at the highlighted diff. If you modify a function signature, they Cmd+Click to see where else it's used. If you introduce a generic struct, they read the interface definition in another file. They think before they speak.

Most open-source AI reviewers can't do this. They suffer from:

Zero Codebase Context: "Why did you use mylog.Info() instead of fmt.Println()?"
Context Window Explosions: Bombarding the LLM with a 150-file MR diff until it forgets your original system prompt.
One-Way Communication: They dump a review and vanish. You can't ask them to elaborate.

🛠️ How AI Review Agent Fixes This

I wanted to build an agent that behaves like an actual colleague. Here is how its pipeline works differently:

1. Agentic Tool Use (The Secret Sauce)

The bot doesn't just statically read the diff. It's equipped with tools like read_file, search_code, and multi_diff.
If it sees you calling a mysterious CacheManager.Get(), it will pause, use search_code to find the CacheManager implementation in the codebase, read it, and then decide if your code is buggy. No more hallucinated assertions.

2. The Interactive Reply Loop 💬

Most bots drop a comment and disappear. AI Review Agent stays in the conversation.
If the AI leaves a comment on your code, you can literally @reply to it on the GitLab thread.
"Actually, I did it this way because of a race condition in the upstream service."
A dedicated Replier Agent wakes up, reads the entire thread history, analyzes the surrounding code context again, and continues the technical debate. It will either apologize and agree with you, or push back if it finds a genuine flaw in your logic.

3. It Actually Learns From Your Team 📈

Every codebase has its own unwritten rules. AI Review Agent is designed to get smarter over time.
It features a background Cron job (Feedback Consolidator) that periodically scans historical human replies and resolved AI comments across your GitLab projects. It extracts "lessons learned" and builds a cached "Repository Best Practices" rulebook.
If your team agreed on a specific logging format last month, the agent remembers it and enforces it on all future PRs.

4. Seamless Webhook & Background Worker Server ⚙️

It’s not just a script you run manually. The AI Review Agent operates as a high-performance Webhook Server.

You configure it on your GitLab project once.
Every time a developer pushes code, the webhook triggers the agent.
Reviews are pushed asynchronously into an intelligent Queue / Worker Pool system with retry logic. So even if the OpenAI API hiccups, your code review is never lost.

5. Interactive CLI (Dry Run Mode)

Are you scared of installing a bot that might spam your entire team on GitLab?
You can run AI Review Agent locally against a live PR via CLI:

./cli review --project-id 123 --mr-id 45 --model claude-3-7-sonnet-20250219

It prints the AI's suggestions directly in your terminal, and lets you interactively type 1, 3, 5 to decide exactly which comments are worth pushing to the live GitLab MR.

🏗️ Built with Go (Clean Architecture)

Under the hood, it’s built entirely in Go 1.25. It uses standard Clean Architecture abstractions making it incredibly easy to extend. It supports graceful degradation, multi-LLM routing (OpenAI, Anthropic, Google Gemini), and relies on a local SQLite or Postgres database to keep track of its asynchronous review jobs and feedback metrics.

🚀 Try It Out

If your team uses GitLab and you're looking for a smarter, less noisy AI reviewer—or if you're just interested in Go-based AI Agents—I'd love for you to check it out.

🔗 GitHub Repository: antlss/gitlab-review-agent

I'm actively looking for feedback, feature requests, and early contributors! Let me know in the comments: What is the most annoying comment an AI reviewer has ever left on your PR?